PayPerByte MCP Server

A Model Context Protocol server that gives AI agents direct access to **PayPerByte — 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.

> 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 Merchant Screen Oracle is $0.10 per verdict: 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.

> - 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

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"*
• Screen a counterparty before you pay it (x402, no setup): *"Screen this domain and payout address before I settle"* → $0.10 real USDC on Base mainnet, signed ALLOW/WARN/BLOCK verdict from the Merchant Screen Oracle with an attestation receipt
• Try it cheap first: *"Get the weather"* / *"Any earthquakes over M4 today?"* → $0.005 / $0.003 real USDC, same attestation receipt on every response — the cheapest way to see verify-before-act work before spending on a verdict
• Subscribe to a stream (testnet): *"Subscribe me to the earthquakes feed"* → auto-approves MockUSDC for ongoing settlement on Arbitrum Sepolia
• 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)*

The live catalog is at **x402.payperbyte.io/feeds** — cryptographically attested, provenance-verifiable 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:

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.

Two paradigms: subscribe vs. buy

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.

Buying a verdict (POST oracle)

GET 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`:

// byte_buy_data tool call — screen a merchant/counterparty before settling
{
  "feed": "merchant-screen",
  "body": { "domain": "example.com", "address": "0x1234…abcd", "observed_price_atomic": "100000" }
}

The paid response returns the signed verdict and an inline verify-before-act result over the `X-BYTE-Attestation` receipt:

{
  "feed": "merchant-screen",
  "paid": true,
  "price": "$0.100000",
  "txHash": "0x…",
  "data": { "answer": { "verdict": "ALLOW", "reasons": ["…"] }, "attestation": { "…": "…" } },
  "verification": { "verified": true, "hashMatch": true, "signerMatch": true,
                    "reason": "receipt verified — bytes intact AND signed by the pinned gateway attester (safe to act)" }
}

Act 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, …).

Tools (15 total)

Discovery (read-only, no wallet)

Subscribe to a stream (requires `PRIVATE_KEY`)

Buy on-demand (requires `PRIVATE_KEY`)

Configuration

Claude Desktop

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

{
  "mcpServers": {
    "payperbyte": {
      "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

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

Environment variables

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

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.

Starter kit

Optional paid kit ($39): the buyer-side agent kit — 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.

Links

• **payperbyte.io** — PayPerByte home
• **x402.payperbyte.io/feeds** — live feed catalog
• **Model Context Protocol** — MCP spec
• **MCP TypeScript SDK**
• **gold-402** — curated directory of live x402 services (PayPerByte is listed)