io.github.0rkz/byte-protocol

Official15 tools

by 0rkz · TypeScript

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

io.github.0rkz/byte-protocol MCP Server

This Model Context Protocol (MCP) server provides AI agents direct access to PayPerByte. It exposes cryptographically attested, provenance-verifiable data feeds, with attestations referenced in the X-BYTE-Attestation header. The referenced PayPerByte model is per-byte data priced at x402 USDC on Base, using EIP-712 attestation.

🛠️ Key Features

MCP server for Model Context Protocol
Direct access to PayPerByte data feeds for AI agents
Cryptographically attested, provenance-verifiable data
Attestation referenced via X-BYTE-Attestation
Pay-per-byte model on Base priced in x402 USDC
EIP-712-attested payments/data

🚀 Use Cases

Agent-commerce and AI-agent data consumption
Using a data marketplace for per-byte feeds
MCP-based integration of attested Web3 data

⚡ Developer Benefits

Uses MCP with toolCount: 15
Developer-visible topics include mcp and model-context-protocol
Standards alignment via EIP-712 attestation

⚠️ Limitations

Source excerpt does not describe specific tools, endpoints, or response formats beyond the attestation header reference

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.

Parameters3

query	string	optional	Topic keyword to search (e.g. 'weather', 'crypto', 'cve')
sortBy	string	optional	Sort field: 'subscribers', 'revenue', 'messages'
limit	number	optional	Max results to return (default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Topic keyword to search (e.g. 'weather', 'crypto', 'cve')",
      "type": "string"
    },
    "sortBy": {
      "description": "Sort field: 'subscribers', 'revenue', 'messages'",
      "type": "string"
    },
    "limit": {
      "description": "Max results to return (default 20)",
      "type": "number",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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

Parameters1

address

string

required

Publisher Ethereum address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Publisher Ethereum address (0x...)"
    }
  },
  "required": [
    "address"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

byte_get_network_stats

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

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

byte_check_subscription

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

Parameters2

subscriber	string	required	Subscriber Ethereum address (0x...)
publisher	string	required	Publisher Ethereum address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber": {
      "type": "string",
      "description": "Subscriber Ethereum address (0x...)"
    },
    "publisher": {
      "type": "string",
      "description": "Publisher Ethereum address (0x...)"
    }
  },
  "required": [
    "subscriber",
    "publisher"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

address

string

required

Ethereum address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Ethereum address (0x...)"
    }
  },
  "required": [
    "address"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

byte_list_feeds

List all active data feeds in the PayPerByte catalog with topics, price-per-call, and frequency (pricePerKB is a deprecated alias).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

subscriber	string	required	Wallet address to list subscriptions for
indexerUrl	string	optional	Optional indexer URL override (default: INDEXER_URL/BYTE_INDEXER_URL env or https://feeds.payperbyte.io)

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "Wallet address to list subscriptions for"
    },
    "indexerUrl": {
      "description": "Optional indexer URL override (default: INDEXER_URL/BYTE_INDEXER_URL env or https://feeds.payperbyte.io)",
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "subscriber"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

publisher	string	required	Publisher address to check
indexerUrl	string	optional	Optional indexer URL override

Raw schema

{
  "type": "object",
  "properties": {
    "publisher": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "Publisher address to check"
    },
    "indexerUrl": {
      "description": "Optional indexer URL override",
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "publisher"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

publisher

string

required

Publisher address to unsubscribe from

Raw schema

{
  "type": "object",
  "properties": {
    "publisher": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "Publisher address to unsubscribe from"
    }
  },
  "required": [
    "publisher"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

publisher	string	required	Publisher Ethereum address (0x...) to subscribe to
skipAllowance	boolean	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "publisher": {
      "type": "string",
      "description": "Publisher Ethereum address (0x...) to subscribe to"
    },
    "skipAllowance": {
      "description": "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.",
      "type": "boolean"
    }
  },
  "required": [
    "publisher"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters6

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

Raw schema

{
  "type": "object",
  "properties": {
    "stake": {
      "type": "string",
      "description": "USDC reputation stake to post, as a decimal string. Default '0' — PayPerByte v1 publishers are unstaked."
    },
    "topic": {
      "type": "string",
      "description": "Data feed topic (e.g. 'eth-price', 'weather-nyc', 'gas-tracker')"
    },
    "expectedSize": {
      "type": "number",
      "description": "Expected payload size in bytes per message"
    },
    "maxSize": {
      "type": "number",
      "description": "Maximum payload size in bytes per message"
    },
    "frequency": {
      "type": "number",
      "description": "Expected publishing frequency in seconds"
    },
    "pricePerKB": {
      "type": "number",
      "description": "Price per kilobyte in USDC (e.g. 0.003)"
    }
  },
  "required": [
    "stake",
    "topic",
    "expectedSize",
    "maxSize",
    "frequency",
    "pricePerKB"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

subscriber	string	required	Subscriber Ethereum address (0x...)
data	string	required	Data payload to publish (will be hashed on-chain)
maxFee	number	required	Maximum fee in USDC willing to pay for this publish (e.g. 0.05)

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber": {
      "type": "string",
      "description": "Subscriber Ethereum address (0x...)"
    },
    "data": {
      "type": "string",
      "description": "Data payload to publish (will be hashed on-chain)"
    },
    "maxFee": {
      "type": "number",
      "description": "Maximum fee in USDC willing to pay for this publish (e.g. 0.05)"
    }
  },
  "required": [
    "subscriber",
    "data",
    "maxFee"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

byte_query_fact

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.

Parameters6

question	string	required	The factual question to ask (e.g. 'What was last night's Lakers vs Warriors score?'). Should be specific and verifiable.
subscriber_address	string	required	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_cost	number	optional	Max response payload bytes you're willing to pay for (defaults to 2000). Billed at the publisher's registered price-per-KB — read it with byte_get_publisher or byte_search_publishers before asking. Publisher refuses if can't fit answer.
topic_filter	string	optional	Optional topic filter (e.g. 'fact-oracle' default; future: 'sports', 'finance').
min_publisher_pqs	number	optional	Minimum PQS to consider (BPS scale, 0-10000). 9000 = Elite-only, 7500 = Premium+.
max_response_latency_ms	number	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "minLength": 3,
      "maxLength": 2048,
      "description": "The factual question to ask (e.g. 'What was last night's Lakers vs Warriors score?'). Should be specific and verifiable."
    },
    "subscriber_address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "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_cost": {
      "description": "Max response payload bytes you're willing to pay for (defaults to 2000). Billed at the publisher's registered price-per-KB — read it with byte_get_publisher or byte_search_publishers before asking. Publisher refuses if can't fit answer.",
      "type": "number",
      "minimum": 100,
      "maximum": 10000
    },
    "topic_filter": {
      "description": "Optional topic filter (e.g. 'fact-oracle' default; future: 'sports', 'finance').",
      "type": "string"
    },
    "min_publisher_pqs": {
      "description": "Minimum PQS to consider (BPS scale, 0-10000). 9000 = Elite-only, 7500 = Premium+.",
      "type": "number",
      "minimum": 0,
      "maximum": 10000
    },
    "max_response_latency_ms": {
      "description": "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.",
      "type": "number",
      "minimum": 5000,
      "maximum": 180000
    }
  },
  "required": [
    "question",
    "subscriber_address"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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, 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 and listed per feed at https://x402.payperbyte.io/feeds — the signed EIP-712 attestation over the exact response bytes proves delivery, not that a verdict itself is correct. Use a dedicated wallet holding only what you intend to spend.

Parameters2

feed	string	required	Feed slug — one of: weather ($0.0050), earthquakes ($0.0030), runtime-eol ($0.020), threat-intel ($0.050), address-reputation ($0.100), pkg-verdict ($0.100), sanctions-screen ($0.100), reasoning-verdict ($0.100), merchant-screen ($0.100), positioning-snapshot ($0.030), cctp-attestation-latency ($0.010), regime-signal ($0.020). Full catalog: https://x402.payperbyte.io/feeds (free GET). (For fact-oracle Q&A use byte_query_fact instead — it uses a different request-response flow.)
body	object	optional	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, earthquakes, …).

Raw schema

{
  "type": "object",
  "properties": {
    "feed": {
      "type": "string",
      "minLength": 1,
      "description": "Feed slug — one of: weather ($0.0050), earthquakes ($0.0030), runtime-eol ($0.020), threat-intel ($0.050), address-reputation ($0.100), pkg-verdict ($0.100), sanctions-screen ($0.100), reasoning-verdict ($0.100), merchant-screen ($0.100), positioning-snapshot ($0.030), cctp-attestation-latency ($0.010), regime-signal ($0.020). Full catalog: https://x402.payperbyte.io/feeds (free GET). (For fact-oracle Q&A use byte_query_fact instead — it uses a different request-response flow.)"
    },
    "body": {
      "description": "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, earthquakes, …).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "feed"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters4

data	string	required	The exact payload bytes the agent received and is about to act on — the raw delivered string, or a 0x-prefixed hex byte string.
expectedHash	string	optional	On-chain payloadHash to verify against (0x + 64 hex), e.g. the payloadHash returned by byte_query_fact or byte_buy_data.
txHash	string	optional	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.
hashMode	string	optional	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).

Raw schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "string",
      "description": "The exact payload bytes the agent received and is about to act on — the raw delivered string, or a 0x-prefixed hex byte string."
    },
    "expectedHash": {
      "description": "On-chain payloadHash to verify against (0x + 64 hex), e.g. the payloadHash returned by byte_query_fact or byte_buy_data.",
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{64}$"
    },
    "txHash": {
      "description": "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.",
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{64}$"
    },
    "hashMode": {
      "description": "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).",
      "type": "string",
      "enum": [
        "raw",
        "canonical"
      ]
    }
  },
  "required": [
    "data"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md13 KBView on GitHub

PayPerByte MCP Server

Smithery listing ·

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

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

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

jsonc

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

jsonc

{
  "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):

json

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

bash

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

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.

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.

Install

Tools (15)

byte_search_publishersbyte_get_publisherbyte_get_network_statsbyte_check_subscriptionbyte_get_token_balancesbyte_list_feedsbyte_list_my_subscriptionsbyte_subscription_health

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.

BYTE_GATEWAY_ATTESTER

Gateway attester address byte_buy_data pins receipts against. Defaults to the current PayPerByte gateway attester (rotated 2026-08-19; previous default 0x77c86a...C472 is retired). Override only if the gateway discloses a rotation you need ahead of a package update - see /.well-known/agent.json receipt.attester and receipt.retiredAttesters.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

io.github.0rkz/byte-protocol MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

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

Buying a verdict (POST oracle)

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

Starter kit

Links

Install

Configuration

Related servers

Subscribe to a stream (requires `PRIVATE_KEY`)

Buy on-demand (requires `PRIVATE_KEY`)