Skip to main content
Glama

PayPerByte MCP Server

Smithery listing · 0rkz/byte-mcp-server 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 — every price is quoted in the 402 challenge and listed per feed at https://x402.payperbyte.io/feeds. Example: the Merchant Screen Oracle 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.

  • 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" → 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

  • 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 — a low-cost 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.

Related MCP server: dyoe-agent-tools-mcp

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

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; live list with prices: https://x402.payperbyte.io/feeds

Subscribe

byte_subscribe

Arbitrum Sepolia — testnet MockUSDC

Continuous streams (every weather update, every new earthquake)

Per-publisher, set in the publisher's on-chain schema — read it with byte_get_publisher

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": "<atomic price the MERCHANT you are screening quoted you>" }
}

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",   // illustrative — the amount the 402 challenge quoted at buy time
  "txHash": "0x…",
  "data": { "answer": { "verdict": "ALLOW", "reasons": ["…"] }, "attestation": { "…": "…" } },
  "verification": { "gatewayVerified": true, "hashMatch": true, "signerMatch": true,
                    "reason": "gateway delivery verified — these exact bytes were signed by the pinned gateway attester […receipt deadline note appended]" }
}

Act only when verification.gatewayVerified === true — the receipt proves the gateway delivered these exact bytes, not that the data is correct. 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)

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, don't act on the data — either the bytes differ from what was attested, or verification wasn't possible (no attestation found, signer mismatch, or neither expectedHash nor txHash supplied). The reason field says which

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. Requires a live fact-oracle publisher — none is broadcasting today, so the call times out until one registers.

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

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

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)

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

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

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.

Available Tools

15 tools
byte_buy_dataAInspect

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, earthquakes, …) need only feed; the 10 POST oracles — runtime-eol, threat-intel, address-reputation, pkg-verdict, sanctions-screen, reasoning-verdict, merchant-screen, positioning-snapshot, cctp-attestation-latency, regime-signal — 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 merchant-screen: $0.10/verdict, a pre-settlement counterparty screen — the signed EIP-712 attestation over the exact response bytes proves delivery, not that the verdict itself is correct). Use a dedicated wallet holding only what you intend to spend.

Inputs: feed (required), body. Returns: data, feed, paid, error, +6 more

byte_check_subscriptionA
Read-onlyIdempotent
Inspect

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

Inputs: publisher (required), subscriber (required). Returns: subscribed

byte_get_network_statsA
Read-onlyIdempotent
Inspect

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

Inputs: no named parameters. Returns: messages, publishers, totalSubscriberFeesUsdc

byte_get_publisherA
Read-onlyIdempotent
Inspect

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

Inputs: address (required). Returns: schema, status, address, messages, +4 more

byte_get_token_balancesA
Read-onlyIdempotent
Inspect

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.

Inputs: address (required). Returns: eth, usdc, address

byte_list_feedsA
Read-onlyIdempotent
Inspect

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

Inputs: no named parameters. Returns: feeds

byte_list_my_subscriptionsA
Read-onlyIdempotent
Inspect

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.

Inputs: subscriber (required), indexerUrl. Returns: subscriptions

byte_publish_dataA
Destructive
Inspect

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.

Inputs: data (required), maxFee (required), subscriber (required). Returns: txHash, success, payloadHash, payloadSize

byte_query_factAInspect

Query a PayPerByte fact-oracle publisher for a signed 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. The signed receipt proves which publisher produced the answer (provenance + tamper-evidence), NOT that the answer is correct — ground your output in the cited sources, not in a truth guarantee. Availability: this requires a registered fact-oracle publisher actively broadcasting; if none is live the call returns a timeout rather than an answer.

Inputs: question (required), subscriber_address (required), topic_filter, max_byte_cost, +2 more. Returns: error, answer, citations, confidence, +7 more

byte_register_publisherA
Destructive
Inspect

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.

Inputs: stake (required), topic (required), maxSize (required), frequency (required), +2 more. Returns: topic, txHash, success, publisher, +3 more

byte_search_publishersA
Read-onlyIdempotent
Inspect

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

Inputs: limit, query, sortBy. Returns: publishers

byte_subscribeAInspect

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.

Inputs: publisher (required), skipAllowance. Returns: txHash, success, publisher, allowanceTxHash

byte_subscription_healthA
Read-onlyIdempotent
Inspect

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.

Inputs: publisher (required), indexerUrl. Returns: signal, publisher, messages7d, messages30d, +5 more

byte_unsubscribeAInspect

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.

Inputs: publisher (required). Returns: status, txHash, publisher, subscriber, +1 more

byte_verify_payloadA
Read-onlyIdempotent
Inspect

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.

Inputs: data (required), txHash, hashMode, expectedHash. Returns: reason, signer, source, txHash, +10 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 15 tools

    Disambiguation4/5

    Each tool targets a distinct resource+action (publisher, subscription, feed, payload, balance), with clear separation between discover/subscribe/buy/publish/verify flows. The closest overlaps are byte_search_publishers vs byte_list_feeds and byte_check_subscription vs byte_list_my_subscriptions, but the descriptions clarify catalog-level discovery vs wallet-specific checks well enough to prevent misselection.

    Naming Consistency4/5

    The dominant pattern is byte_verb_noun (get_publisher, list_feeds, buy_data, verify_payload), and the byte_ prefix gives every tool a strong family identity. Deviations like byte_subscription_health (no verb) and byte_subscribe/byte_unsubscribe (verb-only) are conventional and readable but break the strict pattern.

    Tool Count5/5

    15 tools sits at the top of the well-scoped range, and each tool earns its place across two user roles (subscriber and publisher) plus payment, balance, and verification concerns. The breadth is justified by the data-marketplace domain, which naturally requires discovery, subscription lifecycle, publishing, pay-per-call purchasing, and attestation verification.

    Completeness4/5

    The subscriber lifecycle is fully covered (discover, subscribe, monitor health, unsubscribe), and the publisher side supports register and publish, complemented by pay-per-call purchase, fact-oracle queries, and payload verification. Notable gaps are publisher self-service (no schema/price update, no unregister) and no historical message retrieval beyond counts, but the core v1 workflows have no dead ends.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers