io.github.0rkz/byte-protocol

Official15 tools

by 0rkz · JavaScript

PayPerByte — per-byte data for AI agents: x402 USDC on Base, EIP-712-attested. No token.

Provides per-byte data access for AI agents with blockchain-attested payment on Base network.

Topics

agent-commerceai-agentsarbitrumdata-marketplacedepinmcpmcp-servermodel-context-protocolweb3x402baseeip-712

Captured live from the server via tools/list.

byte_search_publishers

Search PayPerByte publishers by topic and sort order. Returns publisher addresses, topics, subscriber counts, message counts, and price-per-KB.

Parameters (3)

querystring
Topic keyword to search (e.g. 'weather', 'crypto', 'cve')
sortBystring
Sort field: 'subscribers', 'revenue', 'messages'
limitnumber
Max results to return (default 20)

byte_get_publisher

Get on-chain info for a specific PayPerByte publisher: status, subscriber and message counts, USDC revenue, and the registered schema (size bounds, cadence, price-per-KB).

Parameters (1)

addressstringrequired
Publisher Ethereum address (0x...)

byte_get_network_stats

Get PayPerByte network-wide statistics: total publishers, messages streamed, and total subscriber fees settled in USDC.

No parameters.

byte_check_subscription

Check if an address is subscribed to a specific publisher on PayPerByte.

Parameters (2)

subscriberstringrequired
Subscriber Ethereum address (0x...)
publisherstringrequired
Publisher Ethereum address (0x...)

byte_get_token_balances

Get USDC and ETH balances for an address on Arbitrum Sepolia (the on-chain testnet layer — MockUSDC settles subscriptions and fact-oracle queries there). Does NOT show the Base-mainnet USDC balance that byte_buy_data spends.

Parameters (1)

addressstringrequired
Ethereum address (0x...)

byte_list_feeds

List all active data feeds in the PayPerByte catalog with topics, price-per-KB, and frequency.

No parameters.

byte_list_my_subscriptions

List every active subscription for a given wallet address. Each entry has the publisher address, topic, status, when you subscribed, messages received in 7/30 days, USDC spent in 7/30 days, and the timestamp of the last message received. Use this to see what you're currently paying for and decide whether to unsubscribe.

Parameters (2)

subscriberstringrequired
Wallet address to list subscriptions for
indexerUrlstring
Optional indexer URL override (default: INDEXER_URL/BYTE_INDEXER_URL env or https://feeds.payperbyte.io)

byte_subscription_health

Get the content-drift signal for a publisher. Compares their last 7 days of publishing activity (cadence, message count) against their 23-day baseline (days 8-30). Returns 'stable' (steady publishing), 'moderate' (20-50% cadence shift or 24-48h silence), 'significant' (>50% shift or >48h silence), or 'unknown' (new publisher, insufficient baseline). Use this to detect when a publisher you subscribe to has pivoted content or gone dormant.

Parameters (2)

publisherstringrequired
Publisher address to check
indexerUrlstring
Optional indexer URL override

byte_unsubscribe

Unsubscribe from a publisher's data feed. Takes effect next block: no more billing, no more data flow. Reversible — you can resubscribe later via byte_subscribe. Use this when a publisher has pivoted content (check with byte_subscription_health first) or when you simply don't want the feed anymore. Requires PRIVATE_KEY for the connected wallet.

Parameters (1)

publisherstringrequired
Publisher address to unsubscribe from

byte_subscribe

Subscribe to a PayPerByte publisher's data feed. By default also sets USDC allowance to DataStreamLib to type(uint256).max so the subscription doesn't silently lose payments when allowance depletes (the contract's allowance-skip path emits DataStreamed with amount=0 on transferFrom failure rather than reverting). Pass skipAllowance: true to opt out and set a finite cap manually. Requires PRIVATE_KEY.

Parameters (2)

publisherstringrequired
Publisher Ethereum address (0x...) to subscribe to
skipAllowanceboolean
If true, don't bundle the USDC approve(max) call. Default false. Auto-approve is also skipped when the wallet already has ≥ $1000 USDC of allowance to DataStreamLib.

byte_register_publisher

Register as a data publisher on PayPerByte. Registers a schema and the publisher on-chain. Requires PRIVATE_KEY. PayPerByte v1 publishers are first-party and unstaked — leave stake at '0'; a non-zero USDC stake is approved to DataRegistry first if you choose to post one.

Parameters (6)

stakestringrequired
USDC reputation stake to post, as a decimal string. Default '0' — PayPerByte v1 publishers are unstaked.
topicstringrequired
Data feed topic (e.g. 'eth-price', 'weather-nyc', 'gas-tracker')
expectedSizenumberrequired
Expected payload size in bytes per message
maxSizenumberrequired
Maximum payload size in bytes per message
frequencynumberrequired
Expected publishing frequency in seconds
pricePerKBnumberrequired
Price per kilobyte in USDC (e.g. 0.003)

byte_publish_data

Publish data to a subscriber via the PayPerByte DataStream contract. Hashes the payload, records size on-chain, and settles the fee in USDC. Requires PRIVATE_KEY.

Parameters (3)

subscriberstringrequired
Subscriber Ethereum address (0x...)
datastringrequired
Data payload to publish (will be hashed on-chain)
maxFeenumberrequired
Maximum fee in USDC willing to pay for this publish (e.g. 0.05)

byte_query_fact

Query a PayPerByte fact-oracle publisher for a verified factual answer with citations. Posts the question to a registered fact-oracle publisher (topic='fact-oracle'), waits for the on-chain BroadcastStreamed response, and returns the answer plus structured citation URLs. Use for grounding LLM outputs in real-time verified information.

Parameters (6)

questionstringrequired
The factual question to ask (e.g. 'What was last night's Lakers vs Warriors score?'). Should be specific and verifiable.
subscriber_addressstringrequired
Your wallet address. You MUST be subscribed to the chosen publisher (with sufficient USDC escrow) or the publisher's on-chain broadcast will be skipped.
max_byte_costnumber
Max response payload bytes you're willing to pay for (defaults to 2000, ≈$1 at $0.0005/byte). Publisher refuses if can't fit answer.
topic_filterstring
Optional topic filter (e.g. 'fact-oracle' default; future: 'sports', 'finance').
min_publisher_pqsnumber
Minimum PQS to consider (BPS scale, 0-10000). 9000 = Elite-only, 7500 = Premium+.
max_response_latency_msnumber
Max time to wait for the publisher's broadcast (default 30000 ms). Local-LLM publishers (Ollama + Searxng + 3-sample NLI gate) take ~30-60s; Anthropic + passthrough takes ~10-20s. Hard ceiling 180s.

byte_buy_data

Buy a single data packet from any PayPerByte feed via the x402 payment gateway. No subscription, no allowance, no prior on-chain setup — pay-per-call USDC settlement. The MCP server signs an EIP-3009 transferWithAuthorization on behalf of the wallet whose PRIVATE_KEY is configured, the x402 facilitator submits the tx, and the data comes back inline with the on-chain settlement tx hash. Use byte_subscribe instead if you want a continuous stream of broadcasts from a publisher. The catalog of available feed slugs lives at https://x402.payperbyte.io/feeds (free GET). GET data feeds (weather, defi-yields, …) need only `feed`; POST verdict oracles (address-reputation, sanctions-screen, pkg-verdict, reasoning-verdict) additionally require a JSON `body` (the query) — supplying `body` switches this call to POST. Requires PRIVATE_KEY env var on the MCP server and USDC on the configured wallet. NOTE: paid feeds settle REAL USDC on Base mainnet (eip155:8453) — the exact price is quoted in the 402 challenge (flagship address-reputation: $0.05/verdict). Use a dedicated wallet holding only what you intend to spend.

Parameters (2)

feedstringrequired
Feed slug — see https://x402.payperbyte.io/feeds for the live catalog. (For fact-oracle Q&A use byte_query_fact instead — it uses a different request-response flow.)
bodyobject
Optional JSON query body for POST oracles. Supplying it switches the call from GET to POST. Required by the verdict oracles, e.g. address-reputation {domain,address[,amount,chain]}, sanctions-screen {address|name}, pkg-verdict {ecosystem,package[,version]}, reasoning-verdict {subject}. Omit for GET data feeds (weather, defi-yields, …).

byte_verify_payload

Verify-before-act: confirm a data payload an agent is about to act on actually matches what the publisher cryptographically attested to on-chain. Recomputes keccak256 of the received bytes and compares it to the on-chain EIP-712 PayloadAttestation hash. ALWAYS call this on BYTE-sourced data before acting on it; if verified=false the bytes were tampered/corrupted in transit and MUST NOT be used. Anchor the check with EITHER expectedHash (an on-chain payloadHash you already hold, e.g. from byte_query_fact / byte_buy_data) OR txHash (the settlement tx — also recovers the attestation signer and confirms it is the named publisher). Read-only; no wallet or payment required.

Parameters (4)

datastringrequired
The exact payload bytes the agent received and is about to act on — the raw delivered string, or a 0x-prefixed hex byte string.
expectedHashstring
On-chain payloadHash to verify against (0x + 64 hex), e.g. the payloadHash returned by byte_query_fact or byte_buy_data.
txHashstring
Settlement tx hash whose on-chain BroadcastStreamed attestation to verify against. When provided, also recovers the EIP-712 signer and confirms it is the attesting publisher.
hashModestring
How to hash structured payloads: 'raw' (keccak of the utf8 string, default — matches byte_publish_data) or 'canonical' (keccak of key-sorted, whitespace-free JSON).

README.md9 KBView on GitHub

PayPerByte MCP Server

A Model Context Protocol server that gives AI agents direct access to PayPerByte — verified, provenance-first data feeds for AI agents. Agents discover feeds, pay-per-call via x402 (settled in USDC on Base mainnet), or subscribe to on-chain streams (Arbitrum Sepolia testnet). Every paid x402 response carries an EIP-712 PayloadAttestation receipt (X-BYTE-Attestation header) the agent verifies before acting. No tokens, no API keys, no off-chain accounts.

Two rails — read this before setting PRIVATE_KEY.

x402 pay-per-call (byte_buy_data): Base mainnet (eip155:8453), REAL USDC. Paid feeds settle real money — the flagship Address Reputation Oracle is $0.05 per verdict. Use a dedicated wallet holding only what you intend to spend.

On-chain subscribe/publish/query layer (BYTE Library contracts + indexer): Arbitrum Sepolia testnet (chain 421614), MockUSDC. Mainnet for this layer is gated on an external security audit. The EIP-712 attestation signing domain stays anchored at 421614 regardless of which rail you paid on.

One PRIVATE_KEY serves both rails. Never reuse a key holding funds you can't afford to spend.

Quick start

bash

npx -y byte-mcp-server

Wire it into your MCP client (Claude Desktop config below), then your agent can:

Discover feeds: "List the PayPerByte catalog" / "Search publishers for weather"
Buy one packet (x402, no setup): "Check this receiving address before I pay it" → $0.05 real USDC on Base mainnet, signed ALLOW/WARN/BLOCK verdict with an attestation receipt
Subscribe to a stream (testnet): "Subscribe me to the earthquakes feed" → auto-approves MockUSDC for ongoing settlement on Arbitrum Sepolia
Query a fact (testnet): "Ask the fact-oracle who won the last Lakers vs Warriors game" → on-chain signed answer with citations

The live catalog is at x402.payperbyte.io/feeds — verified, provenance-first feeds across weather, markets, code, security, and knowledge.

Verify before acting (ForeSeal)

See the whole verify-before-act loop in one command — no install, no signup, no wallet:

bash

npx @foreseal/demo

It runs locally (no real USDC) and shows an agent ACT on genuine bytes and REFUSE four attacks — a tampered byte, a forged signature, a missing receipt, a forked signing domain — in about a second.

The same primitive ships as two packages you can drop into your own stack:

Kit — @payperbyte/sdk: the buyer verifies a receipt before acting.
Gate — @foreseal/gate: a seller stamps a verifiable receipt on any x402 endpoint.

Mode	Tool	Rail	Best for	Pricing
Buy (x402)	`byte_buy_data`	Base mainnet — real USDC	One-off needs (single snapshot or verdict for this user query)	Per-feed, quoted in the 402 challenge ($0.05 flagship; most feeds cents or less)
Subscribe	`byte_subscribe`	Arbitrum Sepolia — testnet MockUSDC	Continuous streams (every weather update, every new earthquake)	$0.003 / KB per delivery

Buy is zero-setup, pay-as-you-go, and live with real settlement; subscribe delivers every broadcast on the audit-gated testnet layer. Pick by access pattern.

Tools (15 total)

Discovery (read-only, no wallet)

Tool	Description
`byte_search_publishers`	Search publishers by topic and sort order
`byte_list_feeds`	List the active feed catalog with prices and frequencies
`byte_get_publisher`	On-chain info for one publisher (status, subscribers, messages, USDC revenue, schema)
`byte_get_network_stats`	Network-wide stats: publishers, messages, total fees settled
`byte_check_subscription`	Is `subscriber` subscribed to `publisher`?
`byte_list_my_subscriptions`	All active subscriptions for a wallet — last 7d/30d messages + USDC spend
`byte_subscription_health`	Content-drift signal for a publisher: stable / moderate / significant / unknown
`byte_get_token_balances`	USDC + ETH balances on Arbitrum Sepolia
`byte_verify_payload`	Verify-before-act. Recompute `keccak256` of the bytes your agent received and check them against the publisher's on-chain EIP-712 `PayloadAttestation` — anchor with an `expectedHash` you hold or the settlement `txHash` (which also recovers the signer and confirms it's the named publisher). If `verified: false`, the data was tampered/corrupted in transit — don't act on it

Subscribe to a stream (requires `PRIVATE_KEY`)

Tool	Description
`byte_subscribe`	Subscribe to a publisher's stream. Auto-bundles USDC `approve(max)` unless `skipAllowance: true` (closes a silent-payment-failure footgun where the contract's allowance-skip path delivered data with `amount=0`)
`byte_unsubscribe`	Unsubscribe — takes effect next block
`byte_register_publisher`	Register as a data publisher (schema + on-chain registration). v1 is first-party only; stake = 0
`byte_publish_data`	Publish a payload to a subscriber via DataStream (settles fee in USDC). See migration notice above re: r2

Buy on-demand (requires `PRIVATE_KEY`)

Tool	Description
`byte_buy_data`	Buy one packet from any feed via the x402 gateway — real USDC on Base mainnet. No subscription, no allowance. Signs EIP-3009 `transferWithAuthorization` against the 402 challenge; the facilitator settles on-chain. Returns the data + tx hash inline
`byte_query_fact`	Ask a slashable fact-oracle publisher a question. Signed EIP-712 request (binds query to your wallet so leaked queries can't burn your escrow); the answer is broadcast on-chain to your address with citations

Configuration

Claude Desktop

Edit ~/.config/claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

json

{
  "mcpServers": {
    "byte-library": {
      "command": "npx",
      "args": ["-y", "byte-mcp-server"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "RPC_URL": "https://sepolia-rollup.arbitrum.io/rpc",
        "INDEXER_URL": "http://localhost:8080"
      }
    }
  }
}

PRIVATE_KEY is optional — read-only tools work without it. Add it to enable subscribe, publish, buy, and query.

Claude Code

bash

claude mcp add byte-library -- npx -y byte-mcp-server

Environment variables

Variable	Required	Default	Description
`PRIVATE_KEY`	only for write/buy/query tools	—	EOA key. Signs real Base-mainnet USDC for `byte_buy_data` and testnet txs for subscribe/publish/query — use a dedicated wallet
`RPC_URL`	no	`https://sepolia-rollup.arbitrum.io/rpc`	Arbitrum Sepolia RPC (the on-chain read/subscribe layer)
`INDEXER_URL`	no	`https://feeds.payperbyte.io`	PayPerByte indexer API
`BYTE_GATEWAY_URL`	no	`https://x402.payperbyte.io`	x402 gateway base URL (used by `byte_buy_data`)

Network

Two rails, honestly stated:

x402 payment rail (byte_buy_data): Base mainnet (eip155:8453). Paid feeds settle real USDC through the gateway at x402.payperbyte.io; each paid 200 returns an X-BYTE-Attestation EIP-712 receipt over the exact response bytes.
On-chain layer (subscriptions, broadcasts, fact-oracle escrow, indexer): Arbitrum Sepolia (chain 421614). Mainnet for the BYTE Library contracts is gated on an external security audit. The EIP-712 PayloadAttestation signing domain is anchored on 421614 regardless of the payment rail.

Contract addresses are pinned in the bundled config; the npm release ships ready-to-use defaults. No token.

Development

bash

git clone https://github.com/0rkz/byte-mcp-server.git
cd byte-mcp-server
npm install
npm run build && npm start

License

MIT — see LICENSE.

Install

Configuration

Environment variables

PRIVATE_KEYsecret

Ethereum private key for write/buy tools (subscribe, unsubscribe, publish, buy_data). buy_data spends real Base-mainnet USDC — use a dedicated wallet. Not required for read-only tools.

RPC_URL

RPC for the on-chain library + EIP-712 attestation layer (Arbitrum Sepolia, eip155:421614). The x402 buy rail settles USDC on Base mainnet and needs no RPC here. Defaults to Arbitrum Sepolia public RPC.

claude_desktop_config.json

{
  "mcpServers": {
    "byte-protocol": {
      "command": "npx",
      "args": [
        "-y",
        "byte-mcp-server@0.11.10"
      ],
      "env": {
        "PRIVATE_KEY": "<YOUR_PRIVATE_KEY>",
        "RPC_URL": "<YOUR_RPC_URL>"
      }
    }
  }
}

Topics

byte_search_publishers

byte_get_publisher

byte_get_network_stats

byte_check_subscription

byte_get_token_balances

byte_list_feeds

byte_list_my_subscriptions

byte_subscription_health

byte_unsubscribe

byte_subscribe

byte_register_publisher

byte_publish_data

byte_query_fact

byte_buy_data

byte_verify_payload

PayPerByte MCP Server

Quick start

Verify before acting (ForeSeal)

Two paradigms: subscribe vs. buy

Tools (15 total)

Discovery (read-only, no wallet)

Subscribe to a stream (requires PRIVATE_KEY)

Buy on-demand (requires PRIVATE_KEY)

Configuration

Claude Desktop

Claude Code

Environment variables

Network

Development

License

Links

Install

Configuration

Subscribe to a stream (requires `PRIVATE_KEY`)

Buy on-demand (requires `PRIVATE_KEY`)