Skip to main content
Glama

byte-protocol

by io.github.0rkz

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 POST oracles (see https://x402.payperbyte.io/feeds for the live list and each feed's method) 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyNoOptional 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, …).
feedYesFeed 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.)

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
dataNoDecoded feed payload returned by the publisher
feedNoEchoed feed slug
paidNoTrue if an x402 payment was made (false on free/cached feeds)
errorNoError message if the buy failed
payerNoWallet that signed the EIP-3009 authorization
priceNoUSDC paid for this packet (e.g. '$0.003000'); omitted on free feeds
detailNoAdditional error detail, if any
statusNoHTTP status of the (post-payment) gateway response
txHashNox402 settlement transaction hash
verificationNoTwo-leg verify-before-act result: {gatewayVerified, hashMatch, signerMatch, recovered, attester, expired, deadline, checkedAt, embeddedAttestation, reason, note}. gatewayVerified=true means the GATEWAY delivered these exact bytes (signed by the pinned gateway attester) — it does NOT verify the per-feed publisher's embedded attestation (answer.attestation). When embeddedAttestation==='present', verify that leg before trusting the data (see note). expired=true means the receipt's EIP-712 deadline had already passed on arrival (deadline/checkedAt are UNIX-second strings); a freshly minted receipt cannot be expired, so that indicates a replayed/cached response or clock skew and the tool refuses (isError) even if the signature checks out.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (no read-only, no idempotency), the description discloses the EIP-3009 signing, facilitator submission, USDC settlement on Base mainnet, real costs (with examples), required PRIVATE_KEY and USDC balance, and the caveat that the attestation proves delivery but not correctness. This is rich, honest behavior disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-structured, opening with the core purpose and settlement model, then layering in alternatives, parameter details, prerequisites, and a security warning. Every sentence carries information; it is appropriately sized for the complexity of a payment-based tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description leaves no critical gap: it covers prerequisites (PRIVATE_KEY, USDC), settlement network, cost examples, parameter nuances, return behavior (data inline with tx hash), and a dedicated-wallet security note. For a complex transaction tool, it is remarkably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaningful nuance: it explains that supplying body switches the call from GET to POST, reiterates the catalog link, and highlights the specific POST oracles. This goes beyond the schema's literal parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb ('buy') and resource ('data packet from any PayPerByte feed') via the x402 gateway, and the description explicitly contrasts with byte_subscribe and byte_query_fact. An agent can immediately understand what this tool does and how it differs from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly names byte_subscribe for continuous streams and byte_query_fact for fact-oracle Q&A, providing clear conditions for choosing alternatives. It also details the GET vs POST distinction and when body is required, giving unambiguous operational guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All byte-protocol toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.3/5.0
Disambiguation5/5

Each tool targets a distinct action or resource, and overlapping functions (buy_data vs subscribe, check_subscription vs list_my_subscriptions) are explicitly differentiated in descriptions. No two tools appear to do the same thing.

Naming Consistency4/5

Most tools follow the byte_verb_noun pattern (e.g., byte_buy_data, byte_get_publisher), but a few deviate: byte_subscription_health uses a noun phrase, and byte_unsubscribe lacks an explicit object. The consistent byte_ prefix keeps the set recognizable.

Tool Count5/5

15 tools is at the upper edge of the well-scoped range, and each tool serves a distinct purpose within the PayPerByte protocol—discovery, purchasing, publishing, verification, and account management. No redundant or filler tools.

Completeness4/5

Core lifecycle coverage is strong: list/search, subscribe/unsubscribe, buy, publish, register, verify, health, and network stats. Minor gaps exist, such as no explicit tool to fetch historical streamed messages or update a publisher schema, but these are workable.

Resources