{
  "markdown": "# PayPerByte MCP Server\n\n<!-- mcp-name: io.github.0rkz/byte-protocol -->\n\n[![smithery badge](https://smithery.ai/badge/byte/byte-library)](https://smithery.ai/servers/byte/byte-library) [![0rkz/byte-mcp-server MCP server](https://glama.ai/mcp/servers/0rkz/byte-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/0rkz/byte-mcp-server)\n\nA [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI agents direct access to **[PayPerByte](https://www.payperbyte.io)** — cryptographically attested, provenance-verifiable data feeds for AI agents (the `X-BYTE-Attestation` receipt proves delivery-integrity — these are exactly the bytes PayPerByte served and attested under the BYTE Library domain — not that an independent data publisher signed them, and not that the data is correct). 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.\n\n> **Two rails — read this before setting `PRIVATE_KEY`.**\n>\n> - **x402 pay-per-call (`byte_buy_data`): Base mainnet (`eip155:8453`), REAL USDC.** Paid feeds settle real money — every price is quoted in the 402 challenge and listed per feed at https://x402.payperbyte.io/feeds. Example: the [Merchant Screen Oracle](https://x402.payperbyte.io/feeds/merchant-screen) returns a signed ALLOW/WARN/BLOCK check on a merchant's domain and payout address, backed by a signed EIP-712 attestation over the exact response bytes, run before an agent settles an x402 payment to it. Authenticity and delivery-integrity, not a correctness guarantee on the verdict itself — and on the domain, address and price you supply; it does not observe or constrain the address you ultimately settle to. Use a dedicated wallet holding only what you intend to spend.\n> - **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.\n>\n> One `PRIVATE_KEY` serves both rails. Never reuse a key holding funds you can't afford to spend.\n\n## Quick start\n\n```bash\nnpx -y byte-mcp-server\n```\n\nWire it into your MCP client (Claude Desktop config below), then your agent can:\n\n- **Discover** feeds: *\"List the PayPerByte catalog\"* / *\"Search publishers for weather\"*\n- **Screen a counterparty before you pay it** (x402, no setup): *\"Screen this domain and payout address before I settle\"* → real USDC on Base mainnet at the price the 402 challenge quotes, signed ALLOW/WARN/BLOCK verdict from the Merchant Screen Oracle with an attestation receipt\n- **Try it cheap first**: *\"Get the weather\"* / *\"Any earthquakes over M4 today?\"* → real USDC at each feed's listed price (https://x402.payperbyte.io/feeds), same attestation receipt on every response — the cheapest way to see verify-before-act work before spending on a verdict\n- **Subscribe** to a stream (testnet): *\"Subscribe me to the earthquakes feed\"* → auto-approves MockUSDC for ongoing settlement on Arbitrum Sepolia\n- **Query a fact-oracle** (testnet): post a signed EIP-712 question to a registered fact-oracle publisher for an on-chain signed answer with citations — *when a fact-oracle publisher is live (none is broadcasting today; the tool times out until one registers and broadcasts)*\n\nThe live catalog is at **[x402.payperbyte.io/feeds](https://x402.payperbyte.io/feeds)** — cryptographically attested, provenance-verifiable feeds across weather, markets, code, security, and knowledge.\n\n## Verify before acting (ForeSeal)\n\nSee the whole verify-before-act loop in one command — no install, no signup, no wallet:\n\n```bash\nnpx @foreseal/demo\n```\n\nIt 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.\n\nThe same primitive ships as two packages you can drop into your own stack:\n\n- **Kit** — [`@payperbyte/sdk`](https://www.npmjs.com/package/@payperbyte/sdk): the buyer verifies a receipt before acting.\n- **Gate** — [`@foreseal/gate`](https://www.npmjs.com/package/@foreseal/gate): a seller stamps a verifiable receipt on any x402 endpoint.\n\n## Two paradigms: subscribe vs. buy\n\n| Mode | Tool | Rail | Best for | Pricing |\n|---|---|---|---|---|\n| **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; live list with prices: https://x402.payperbyte.io/feeds |\n| **Subscribe** | `byte_subscribe` | Arbitrum Sepolia — testnet MockUSDC | Continuous streams (every weather update, every new earthquake) | $0.003 / KB per delivery |\n\nBuy 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.\n\n### Buying a verdict (POST oracle)\n\nGET data feeds need only a `feed`. Any feed whose `method` includes POST (live list: https://x402.payperbyte.io/feeds) takes the query as a `body` — `byte_buy_data` switches the call from GET to POST automatically. The **verdict oracles** — feeds that return a signed ALLOW/WARN/BLOCK — are `merchant-screen`, `address-reputation`, `sanctions-screen`, `pkg-verdict`, `reasoning-verdict`:\n\n```jsonc\n// byte_buy_data tool call — screen a merchant/counterparty before settling\n{\n  \"feed\": \"merchant-screen\",\n  \"body\": { \"domain\": \"example.com\", \"address\": \"0x1234…abcd\", \"observed_price_atomic\": \"100000\" }\n}\n```\n\nThe paid response returns the signed verdict **and** an inline verify-before-act result over the `X-BYTE-Attestation` receipt:\n\n```jsonc\n{\n  \"feed\": \"merchant-screen\",\n  \"paid\": true,\n  \"price\": \"$0.100000\",   // illustrative — the amount the 402 challenge quoted at buy time\n  \"txHash\": \"0x…\",\n  \"data\": { \"answer\": { \"verdict\": \"ALLOW\", \"reasons\": [\"…\"] }, \"attestation\": { \"…\": \"…\" } },\n  \"verification\": { \"verified\": true, \"hashMatch\": true, \"signerMatch\": true,\n                    \"reason\": \"receipt verified — bytes intact AND signed by the pinned gateway attester (safe to act)\" }\n}\n```\n\nAct only when `verification.verified === true` — the receipt proves provenance and integrity, not correctness. Other POST bodies: `address-reputation {domain,address}`, `sanctions-screen {address|name}`, `pkg-verdict {ecosystem,package[,version]}`, `reasoning-verdict {subject}`. Omit `body` entirely for GET data feeds (weather, earthquakes, …).\n\n## Tools (15 total)\n\n### Discovery (read-only, no wallet)\n\n| Tool | Description |\n|---|---|\n| `byte_search_publishers` | Search publishers by topic and sort order |\n| `byte_list_feeds` | List the active feed catalog with prices and frequencies |\n| `byte_get_publisher` | On-chain info for one publisher (status, subscribers, messages, USDC revenue, schema) |\n| `byte_get_network_stats` | Network-wide stats: publishers, messages, total fees settled |\n| `byte_check_subscription` | Is `subscriber` subscribed to `publisher`? |\n| `byte_list_my_subscriptions` | All active subscriptions for a wallet — last 7d/30d messages + USDC spend |\n| `byte_subscription_health` | Content-drift signal for a publisher: stable / moderate / significant / unknown |\n| `byte_get_token_balances` | USDC + ETH balances on Arbitrum Sepolia |\n| `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 |\n\n### Subscribe to a stream (requires `PRIVATE_KEY`)\n\n| Tool | Description |\n|---|---|\n| `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`) |\n| `byte_unsubscribe` | Unsubscribe — takes effect next block |\n| `byte_register_publisher` | Register as a data publisher (schema + on-chain registration). v1 is first-party only; stake = 0 |\n| `byte_publish_data` | Publish a payload to a subscriber via DataStream (settles fee in USDC). See migration notice above re: r2 |\n\n### Buy on-demand (requires `PRIVATE_KEY`)\n\n| Tool | Description |\n|---|---|\n| `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 |\n| `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. *Requires a live fact-oracle publisher — none is broadcasting today, so the call times out until one registers.* |\n\n## Configuration\n\n### Claude Desktop\n\nEdit `~/.config/claude/claude_desktop_config.json` (Linux) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"payperbyte\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"byte-mcp-server\"],\n      \"env\": {\n        \"PRIVATE_KEY\": \"0x...\",\n        \"RPC_URL\": \"https://sepolia-rollup.arbitrum.io/rpc\",\n        \"INDEXER_URL\": \"http://localhost:8080\"\n      }\n    }\n  }\n}\n```\n\n`PRIVATE_KEY` is optional — read-only tools work without it. Add it to enable subscribe, publish, buy, and query.\n\n### Claude Code\n\n```bash\nclaude mcp add payperbyte -- npx -y byte-mcp-server\n```\n\n### Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `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 |\n| `RPC_URL` | no | `https://sepolia-rollup.arbitrum.io/rpc` | Arbitrum Sepolia RPC (the on-chain read/subscribe layer) |\n| `INDEXER_URL` | no | `https://feeds.payperbyte.io` | PayPerByte indexer API |\n| `BYTE_GATEWAY_URL` | no | `https://x402.payperbyte.io` | x402 gateway base URL (used by `byte_buy_data`) |\n| `BYTE_GATEWAY_ATTESTER` | no | current gateway attester (`0xB48CCc9e3ab67041e3b5D09700138E45cda6AeA8`, rotated 2026-08-19) | Attester address `byte_buy_data` pins the delivery receipt against. If the gateway rotates before this package updates, set this to the new `receipt.attester` from `/.well-known/agent.json` — a stale pin fail-closes buys AFTER payment settles |\n| `MAX_PAYMENT_USDC` | no | — (uncapped) | Server-side spend cap for `byte_buy_data`, in decimal USDC (e.g. `0.25`). When set, any 402 quote above the cap is refused before signing; unset means no cap — a dedicated thin wallet remains the hard backstop |\n\n## Network\n\nTwo rails, honestly stated:\n\n- **x402 payment rail (`byte_buy_data`): Base mainnet (`eip155:8453`).** Paid feeds settle real USDC through the gateway at [x402.payperbyte.io](https://x402.payperbyte.io); each paid 200 returns an `X-BYTE-Attestation` EIP-712 receipt over the exact response bytes.\n- **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.\n\nContract addresses are pinned in the bundled config; the npm release ships ready-to-use defaults. No token.\n\n## Development\n\n```bash\ngit clone https://github.com/0rkz/byte-mcp-server.git\ncd byte-mcp-server\nnpm install\nnpm run build && npm start\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Starter kit\n\nOptional paid kit ($39): the [buyer-side agent kit](https://payperbyte.gumroad.com/l/pvykda) — an agent that buys and verifies feeds, with drop-in Claude Desktop / Claude Code / Cursor config and a free 30-minute readiness call included. The npm packages are and stay free MIT — the kit sells the assembled setup.\n\n## Links\n\n- **[payperbyte.io](https://www.payperbyte.io)** — PayPerByte home\n- **[x402.payperbyte.io/feeds](https://x402.payperbyte.io/feeds)** — live feed catalog\n- **[Model Context Protocol](https://modelcontextprotocol.io/)** — MCP spec\n- **[MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)**\n- **[gold-402](https://github.com/Haustorium12/gold-402)** — curated directory of live x402 services (PayPerByte is listed)\n",
  "bytes": 12890,
  "sha": "7cd55afec4344422ad04e4a471d6830ab61e1a6deffcf6574875e45459b15359",
  "repo_slug": "0rkz/byte-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_0rkz_byte_protocol_1e4ee063/readme"
}