# PayPerByte — full agent brief

> PayPerByte is a verified, provenance-first data layer for AI agents. Agents discover and pay-per-call (or subscribe) for first-party data feeds and oracles. Pay-per-call is keyless x402 USDC settled on Base mainnet — a wallet signs an EIP-3009 `transferWithAuthorization`, the facilitator pays gas, and there is no API key, no signup, and no token. Every paid response carries an signed EIP-712 `PayloadAttestation`, returned in the `X-BYTE-Attestation` receipt header, so an agent can verify the exact bytes and the signer before acting on the data.

This document is the complete plain-text brief for AI agents and the tools that ingest agent-readable context. The short index is at https://www.payperbyte.io/llms.txt.

---

## What PayPerByte is for

AI agents need data they can trust enough to act on. The web gives agents data with no provenance: you cannot prove who produced a number or that it was not altered in transit. PayPerByte closes that gap. Each feed is published by a known first-party publisher who signs an EIP-712 `PayloadAttestation`. When an agent fetches a payload, it can recompute `keccak256(canonical bytes)` and check it against the attested hash — and recover the signer — before trusting the data.

The wedge is two things, together:

1. Per-byte, verifiable data. You pay for exactly the bytes you consume, and every byte is provenance-stamped.
2. Verify-before-act. The agent does not have to assume the data is intact. It can prove it. If verification fails, the agent should not act on the payload — it was tampered with or corrupted in transit.

There is no token. Settlement is in external USDC (ERC-20). Governance and quality live in the protocol contracts, not in a sold asset.

## The flagship — Address Reputation Oracle

The lead use case is an **agentic-payment go/no-go**: before an autonomous agent releases USDC, ask whether the destination is safe.

```
POST https://x402.payperbyte.io/feeds/address-reputation       $0.10 / verdict
Body: {"domain":"...","address":"0x...","amount":1000000,"chain":"base"}
Pay:  x402, USDC on Base mainnet (eip155:8453)
```

An unpaid request returns the full HTTP 402 payment challenge (no signup, no API key). A paid `200` returns a signed `ALLOW` / `WARN` / `BLOCK` verdict from the frozen `ar-v1` ruleset (RDAP/TLS/DNS/Wayback domain signals + on-chain receiving-address signals + a curated known-bad blocklist). The differentiator vs. an unsigned vendor score: a wrong verdict here is an artifact — signed bytes, a recoverable signer, a frozen ruleset, and `POST /verify` reproducibility.

## Network and status (read this before integrating)

- **Pay-per-call settlement: Base mainnet, chain id `8453`, CAIP-2 `eip155:8453`, in USDC (ERC-20).** The x402 gateway at https://x402.payperbyte.io is live; an unpaid feed request returns HTTP 402 with the payment challenge.
- **EIP-712 attestation domain: anchored on Arbitrum, chain id `421614`** (literal domain name `BYTE Library`). This is a fixed signing namespace, not the settlement rail — flipping it per-rail would fork the consensus domain and break every prior verdict's reproducibility. A **mainnet attestation anchor (Arbitrum One) is pending an external security audit.** Signatures and byte-integrity are real today.
- The streaming/subscription path (`byte_subscribe` / the `StreamSubscription` escrow) and on-chain attestation reads run against that Arbitrum (chainId `421614`) domain.
- No token. No external-user, revenue, or traction claims are made. The loop is dogfooded; external adoption is the open question, stated honestly.
- Read-only discovery tools need no wallet. Paid x402 calls need a wallet holding USDC on Base mainnet.

## Two ways to pay: subscribe vs. buy

| Mode | How | Best for | Price |
|---|---|---|---|
| Subscribe | `byte_subscribe` (MCP) or the `StreamSubscription` escrow | Continuous streams — every update, every new event | $0.003 USDC / KB per delivery |
| Buy (x402) | `byte_buy_data` (MCP) or raw HTTP 402 against the gateway | One-off needs — a single snapshot for this query | $0.005 USDC / KB per call, $0.001 floor |

Subscribe is cheaper per byte and delivers every broadcast; buy is zero-setup and pay-as-you-go. Pick by access pattern, not by price alone. Per-feed price is fixed in the manifest, computed as `max(floor, ceil(expectedSizeBytes / 1024 × pricePerKB))` (the per-KB rate in that formula is the gateway's own; /discover and the generated tool catalogs expose the resulting fixed per-feed value as `pricePerCall`, and their `pricePerKB` field is a deprecated alias of that per-call value, not the per-KB rate), except the decision-priced verdict oracles (address-reputation, sanctions-screen, pkg-verdict, reasoning-verdict — $0.10/verdict).

## Verify-before-act (the core capability)

Every paid `200` carries two independent receipts:

1. The **embedded EIP-712 `PayloadAttestation`** over the canonical payload bytes — proves *who produced this exact payload* (the publisher).
2. The **`X-BYTE-Attestation` response header** — the gateway attester signs the exact response body — proves *these bytes came through the paid rail unmodified*.

To verify either one:

1. Take the canonical bytes you received.
2. Recompute `keccak256` of those bytes.
3. Compare against the attested hash — anchor with an `expectedHash` you already hold, or the settlement `txHash` (which also recovers the signer and confirms it is the named publisher).
4. If it does not match, the data was tampered with or corrupted in transit. Do not act on it.

In MCP this is the `byte_verify_payload` tool. In the SDK it is `verifyPayload(bytes, attestedHash)` (throws `HashMismatchError` on mismatch). This step is what makes PayPerByte data safe to wire into downstream agent decisions.

---

## Path A — MCP (recommended for agents in Claude / Cursor / Windsurf / Cline)

Install: `npx -y byte-mcp-server`

- npm package: `byte-mcp-server` (latest published on npm)
- Machine id / mcpName: `io.github.0rkz/byte-protocol`
- Hosted remote (streamable-HTTP): https://mcp.payperbyte.io/mcp
- Read-only discovery tools need no wallet and no config. Write/buy/query tools need `PRIVATE_KEY` set. Pay-per-call (`byte_buy_data`) settles the gateway's x402 challenge in USDC on Base mainnet, so fund that wallet with a small amount of Base USDC. `RPC_URL` points at the Arbitrum (chainId `421614`) attestation domain used for subscribe/publish/verify reads.

Claude Desktop config:

```json
{
  "mcpServers": {
    "byte-library": {
      "command": "npx",
      "args": ["-y", "byte-mcp-server"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "RPC_URL": "https://sepolia-rollup.arbitrum.io/rpc"
      }
    }
  }
}
```

Claude Code: `claude mcp add byte-library -- npx -y byte-mcp-server`

### Tools (15 total)

Discovery (read-only, no wallet):

- `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 a subscriber subscribed to a 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 the configured attestation-domain chain (Arbitrum, chainId `421614`).
- `byte_verify_payload` — Verify-before-act. Recompute keccak256 of received bytes and check against the signed EIP-712 PayloadAttestation. If `verified: false`, do not act on the data.

Subscribe (requires `PRIVATE_KEY`):

- `byte_subscribe` — Subscribe to a publisher's stream. Auto-bundles USDC `approve(max)` unless `skipAllowance: true`.
- `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; signs the EIP-712 attestation).

Buy on-demand (requires `PRIVATE_KEY`):

- `byte_buy_data` — Buy one packet from any feed via the x402 gateway. No subscription, no allowance. Signs EIP-3009 `transferWithAuthorization` against the gateway's challenge (USDC on Base mainnet); the facilitator settles on-chain. Returns data + tx hash inline.
- `byte_query_fact` — Ask a slashable fact-oracle a question. Signed EIP-712 request (binds the query to your wallet so a leaked query cannot burn your escrow); the answer is broadcast on-chain to your address with citations.

### Typical agent flow

1. `byte_list_feeds` — find the feed that answers the user's question.
2. `byte_buy_data` (one-off) or `byte_subscribe` (recurring) — pay per byte in USDC.
3. `byte_verify_payload` — confirm the bytes against the on-chain attestation (and the `X-BYTE-Attestation` header).
4. Act on the verified data; cite the `txHash` as provenance.

---

## Path B — Raw x402 HTTP (any language)

The gateway lives at https://x402.payperbyte.io. Hit it directly when you are outside an MCP client.

1. Discover: `curl https://x402.payperbyte.io/feeds` returns the live catalog with per-feed price, expected payload size, provenance, and disclaimer category.
2. Request unpaid: `curl -i https://x402.payperbyte.io/feeds/weather` returns HTTP 402 with the x402 payment challenge (asset, amount, recipient, deadline, network `eip155:8453`).
3. Pay + replay: use an x402 client library to sign the EIP-3009 `transferWithAuthorization` and retry. The facilitator settles on Base mainnet and the data is returned with an `X-BYTE-Attestation` receipt header.

POST oracles (address-reputation, sanctions-screen, pkg-verdict, reasoning-verdict, positioning-snapshot — plus the POST query paths on threat-intel and runtime-eol) take a JSON request body and return the signed answer.

### Machine-readable surfaces (all free, ungated)

- Feed catalog: https://x402.payperbyte.io/feeds
- OpenAPI 3.1 contract: https://x402.payperbyte.io/openapi.json — every paid operation declares its x402 payment security scheme, input/output schemas, and price.
- x402 resource manifest: https://x402.payperbyte.io/.well-known/x402.json (aliases: `/x402-manifest`, `/.well-known/x402`) — all payable resources with per-feed price, accepts, and provenance, settled on Base mainnet (`eip155:8453`).
- A2A agent card: https://x402.payperbyte.io/.well-known/agent.json — every feed as a callable skill, the x402 payment surface, and the `X-BYTE-Attestation` receipt block.
- Discovery API (marketplace): https://api.payperbyte.io/discover

---

## Live feed catalog

Prices are per call on the x402 gateway, settled in USDC on Base mainnet (`eip155:8453`). `provenance: eip712-attested` means an signed EIP-712 `PayloadAttestation` publisher feed; `first-party` means a bespoke first-party upstream relay. threat-intel and runtime-eol are dual-pattern: a GET latest-digest and a POST synchronous-query path on the same endpoint.

| Method | Endpoint | Feed | Price | ~Bytes | Provenance | Update | Category |
|---|---|---|---|---|---|---|---|
| POST | /feeds/address-reputation | Address Reputation Oracle (flagship) — signed ALLOW/WARN/BLOCK go/no-go for (domain, address, amount, chain) | $0.100 | 2500 | first-party | on-demand | commerce |
| POST | /feeds/sanctions-screen | Sanctions Screen Oracle — signed, version-pinned OFAC SDN + Consolidated screening on an address or name | $0.100 | 2500 | first-party | on-demand | legal |
| POST | /feeds/pkg-verdict | Package Verdict Oracle — signed ALLOW/WARN/BLOCK on installing a package@version (OSV.dev + typosquat + registry signals) | $0.100 | 2500 | first-party | on-demand | general |
| POST | /feeds/reasoning-verdict | Reasoning Verdict Oracle — signed ALLOW/WARN/BLOCK/ABSTAIN + 0–100 score on an action context, from a local model | $0.100 | 2200 | first-party | on-demand | general |
| POST | /feeds/positioning-snapshot | Positioning Snapshot Oracle — cross-venue perp funding + open interest (Hyperliquid, dYdX v4, Aevo) | $0.030 | 7480 | first-party | on-demand | financial |
| GET/POST | /feeds/threat-intel | Security Advisories Digest — recent CVE highlights + CISA KEV entries (NVD, CISA) | $0.050 | 5300 | eip712-attested | 3600s | general |
| GET/POST | /feeds/runtime-eol | Runtime EOL — end-of-life dates for runtimes/frameworks/OSes | $0.020 | 14200 | eip712-attested | daily | general |
| GET | /feeds/weather | Weather (US, multi-city) — NWS forecasts for NYC/LA/Chicago/Houston/Miami | $0.005 | 4400 | eip712-attested | 3600s | general |
| GET | /feeds/earthquakes | Earthquakes — USGS recent earthquakes worldwide (M2.5+) | $0.003 | 300 | eip712-attested | 900s | general |

The canonical, self-updating list with full per-feed `accepts` + provenance is the manifest at https://x402.payperbyte.io/.well-known/x402.json. Every feed response carries an `X-BYTE-Disclaimer-Category` header (financial / legal / medical / commerce / civic / scientific / general). Data is informational and not financial, legal, or medical advice. Verify before acting.

## Architecture (contracts)

BYTE Library v1 is a lean core, no token, settlement in external USDC. The on-chain contracts (the attestation domain) are anchored on Arbitrum (chainId `421614`); a mainnet anchor is pending audit. x402 pay-per-call settles on Base mainnet via the gateway facilitator.

- DataRegistry — publisher registration, feed/subscriber discovery.
- SchemaRegistry — feed schema (size, frequency, price) + methodology references.
- DataStream — per-call / per-byte payload delivery + USDC settlement; emits the EIP-712 `PayloadAttestation`.
- StreamSubscription — USDC-escrow subscriptions; per-message fees drawn from the budget.

## Pricing reference

- Pay-per-call (x402, buy): $0.005 USDC / KB, $0.001 model floor. Cheapest live feed today: $0.003/call (earthquakes).
- Subscribe: $0.003 USDC / KB per delivery (cheaper per byte; every broadcast delivered).
- Verdict oracles (address-reputation, sanctions-screen, pkg-verdict, reasoning-verdict): $0.10 per verdict, decision-priced.

## Brand and identifiers

- Display brand: PayPerByte.
- Machine ids: npm `byte-mcp-server`, mcpName `io.github.0rkz/byte-protocol`.
- EIP-712 domain literal: `BYTE Library` (consensus-critical; the on-chain attestation domain — never renamed).

## Links

- Home: https://www.payperbyte.io
- Quickstart: https://www.payperbyte.io/docs/quickstart
- Gateway feed catalog: https://x402.payperbyte.io/feeds
- OpenAPI: https://x402.payperbyte.io/openapi.json
- x402 manifest: https://x402.payperbyte.io/.well-known/x402.json
- Agent card: https://x402.payperbyte.io/.well-known/agent.json
- MCP server (npm): https://www.npmjs.com/package/byte-mcp-server
- MCP server (source): https://github.com/0rkz/byte-mcp-server
- Discovery API: https://api.payperbyte.io/discover