byte-protocol

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

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

{
  "type": "object",
  "properties": {
    "publishers": {
      "description": "Matching publishers, sorted by the requested field",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "Publisher Ethereum address (0x...)"
          },
          "topic": {
            "description": "Registered topic slug",
            "type": "string"
          },
          "subscribers": {
            "description": "Active subscriber count",
            "type": "number"
          },
          "messages": {
            "description": "Total messages published",
            "type": "number"
          },
          "pricePerKB": {
            "description": "Price per KB in USDC",
            "type": "number"
          }
        },
        "required": [
          "address"
        ],
        "additionalProperties": {}
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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

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

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Publisher Ethereum address"
    },
    "status": {
      "description": "On-chain publisher status",
      "type": "string"
    },
    "subscribers": {
      "description": "Active subscriber count",
      "type": "number"
    },
    "messages": {
      "description": "Total messages published",
      "type": "number"
    },
    "revenueUsdc": {
      "description": "Total USDC revenue (decimal string)",
      "type": "string"
    },
    "registeredAt": {
      "description": "Unix timestamp of publisher registration",
      "type": "number"
    },
    "lastActive": {
      "description": "Unix timestamp of last on-chain activity",
      "type": "number"
    },
    "schema": {
      "description": "Registered schema (topic, sizes, cadence, price)"
    }
  },
  "required": [
    "address"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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

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

{
  "type": "object",
  "properties": {
    "publishers": {
      "description": "Active publisher count network-wide",
      "type": "number"
    },
    "messages": {
      "description": "Total messages streamed all-time",
      "type": "number"
    },
    "totalSubscriberFeesUsdc": {
      "description": "Total subscriber fees settled (USDC, decimal string)",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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

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

{
  "type": "object",
  "properties": {
    "subscribed": {
      "type": "boolean",
      "description": "True if the subscriber has an active subscription to the publisher"
    }
  },
  "required": [
    "subscribed"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

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

{
  "type": "object",
  "properties": {
    "usdc": {
      "description": "USDC balance as a decimal string in whole USDC (e.g. '12.5') — already scaled by 6 decimals, not atomic units",
      "type": "string"
    },
    "eth": {
      "description": "ETH balance as a decimal string in whole ETH (e.g. '0.01') — already scaled by 18 decimals, not wei",
      "type": "string"
    },
    "address": {
      "description": "Echoed address",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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

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

{
  "type": "object",
  "properties": {
    "feeds": {
      "description": "Catalog of active feeds",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "publisher": {
            "description": "Publisher address for the feed",
            "type": "string"
          },
          "topic": {
            "description": "Topic identifier",
            "type": "string"
          },
          "pricePerKB": {
            "description": "DEPRECATED (misnamed): identical to pricePerCall — the same gateway-reported per-call price, not a per-KB rate. Use pricePerCall. Removal is scheduled for a future minor, not before 0.14.",
            "type": "string"
          },
          "pricePerCall": {
            "description": "Per-call price exactly as the gateway catalog reports it — normally the catalog's `price`, a dollar-formatted string (examples: '$0.0050', '$0.100'); if the catalog supplies only `priceAtomic`, that atomic µUSDC value (e.g. '5000') passes through instead; empty string if it supplies neither. This server does not normalize or convert it, so do not assume either unit. The 402 challenge is the source of truth for what you will actually pay.",
            "type": "string"
          },
          "frequency": {
            "description": "Expected publish cadence in seconds",
            "type": "number"
          }
        },
        "additionalProperties": {}
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

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

{
  "type": "object",
  "properties": {
    "subscriptions": {
      "description": "Active subscriptions for the given wallet",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "publisher": {
            "description": "Publisher address subscribed to",
            "type": "string"
          },
          "topic": {
            "description": "Publisher topic",
            "type": "string"
          },
          "status": {
            "description": "Subscription status (string label or numeric code)",
            "anyOf": [
              {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "subscribedAt": {
            "description": "Unix timestamp of subscribe tx",
            "anyOf": [
              {
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "string"
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "messages7d": {
            "description": "Messages received in last 7 days",
            "type": "number"
          },
          "messages30d": {
            "description": "Messages received in last 30 days",
            "type": "number"
          },
          "spend7dUsdc": {
            "description": "USDC spent in last 7 days (decimal string)",
            "type": "string"
          },
          "spend30dUsdc": {
            "description": "USDC spent in last 30 days (decimal string)",
            "type": "string"
          },
          "lastMessageAt": {
            "description": "Unix timestamp of most recent message",
            "anyOf": [
              {
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "string"
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": {}
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

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

{
  "type": "object",
  "properties": {
    "publisher": {
      "description": "Publisher address checked",
      "type": "string"
    },
    "signal": {
      "description": "Content-drift bucket for the publisher",
      "type": "string",
      "enum": [
        "stable",
        "moderate",
        "significant",
        "unknown"
      ]
    },
    "messages7d": {
      "description": "Messages in the last 7 days",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "messages30d": {
      "description": "Messages in the last 30 days",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "messages_7d": {
      "description": "Messages in the last 7 days (indexer key)",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "messages_30d": {
      "description": "Messages in the last 30 days (indexer key)",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "silence_hours": {
      "description": "Hours since the last message (null if never)",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "cadence_drift_bps": {
      "description": "Cadence drift vs 23-day baseline (bps)",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "volume_ratio_bps": {
      "description": "7d/baseline volume ratio (bps)",
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": {}
}

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.

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

{
  "type": "object",
  "properties": {
    "subscriber": {
      "description": "Subscriber address (the signer)",
      "type": "string"
    },
    "publisher": {
      "description": "Publisher unsubscribed from",
      "type": "string"
    },
    "txHash": {
      "description": "Unsubscribe transaction hash",
      "type": "string"
    },
    "status": {
      "description": "Receipt status ('success' | 'reverted')",
      "type": "string"
    },
    "blockNumber": {
      "description": "Block number the tx landed in",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

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

{
  "type": "object",
  "properties": {
    "success": {
      "description": "True if subscribe landed on-chain",
      "type": "boolean"
    },
    "txHash": {
      "description": "Subscribe transaction hash",
      "type": "string"
    },
    "allowanceTxHash": {
      "description": "USDC approve(max) transaction hash, if bundled",
      "type": "string"
    },
    "publisher": {
      "description": "Publisher subscribed to",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

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

{
  "type": "object",
  "properties": {
    "success": {
      "description": "True if registration landed on-chain",
      "type": "boolean"
    },
    "txHash": {
      "description": "Publisher-registration transaction hash",
      "type": "string"
    },
    "schemaTxHash": {
      "description": "Schema-registration transaction hash",
      "type": "string"
    },
    "approveTxHash": {
      "description": "USDC stake approval tx hash, if a non-zero stake was posted",
      "type": "string"
    },
    "publisher": {
      "description": "Registered publisher address (the signer)",
      "type": "string"
    },
    "stakeUsdc": {
      "description": "USDC stake posted (decimal string; '0' for v1 first-party)",
      "type": "string"
    },
    "topic": {
      "description": "Registered feed topic",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

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

{
  "type": "object",
  "properties": {
    "success": {
      "description": "True if publish landed on-chain",
      "type": "boolean"
    },
    "txHash": {
      "description": "Publish transaction hash",
      "type": "string"
    },
    "payloadSize": {
      "description": "Payload size recorded on-chain (bytes)",
      "type": "number"
    },
    "payloadHash": {
      "description": "keccak256 of the payload as recorded on-chain",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

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

{
  "type": "object",
  "properties": {
    "answer": {
      "description": "Publisher's grounded answer to the question",
      "type": "string"
    },
    "citations": {
      "description": "URLs/sources cited by the publisher in support of the answer",
      "type": "array",
      "items": {}
    },
    "publisher_address": {
      "description": "Publisher address that fulfilled the query",
      "type": "string"
    },
    "publisher_pqs": {
      "description": "Publisher quality score (PQS) at fulfillment",
      "type": "number"
    },
    "confidence": {
      "description": "Publisher-reported confidence (0-1)",
      "type": "number"
    },
    "request_id": {
      "description": "Request id binding the query to this answer",
      "type": "string"
    },
    "payload_hash": {
      "description": "keccak256 of the response payload",
      "type": "string"
    },
    "response_size_bytes": {
      "description": "Size of the response payload (bytes)",
      "type": "number"
    },
    "publisher_tx_or_status": {
      "description": "Delivery status or settlement reference",
      "type": "string"
    },
    "elapsed_ms": {
      "description": "End-to-end time to obtain the answer (ms)",
      "type": "number"
    },
    "error": {
      "description": "Error message if the query failed (no eligible publisher, broadcast timeout, etc.)",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": {}
}

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

{
  "type": "object",
  "properties": {
    "feed": {
      "type": "string",
      "minLength": 1,
      "description": "Feed 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.)"
    },
    "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#"
}

{
  "type": "object",
  "properties": {
    "feed": {
      "description": "Echoed feed slug",
      "type": "string"
    },
    "paid": {
      "description": "True if an x402 payment was made (false on free/cached feeds)",
      "type": "boolean"
    },
    "price": {
      "description": "USDC paid for this packet as a 6-decimal dollar string (format example: '$0.001234'); omitted on free feeds",
      "type": "string"
    },
    "txHash": {
      "description": "x402 settlement transaction hash",
      "type": "string"
    },
    "payer": {
      "description": "Wallet that signed the EIP-3009 authorization",
      "type": "string"
    },
    "status": {
      "description": "HTTP status of the (post-payment) gateway response",
      "type": "number"
    },
    "data": {
      "description": "Decoded feed payload returned by the publisher"
    },
    "verification": {
      "description": "Two-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.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "error": {
      "description": "Error message if the buy failed",
      "type": "string"
    },
    "detail": {
      "description": "Additional error detail, if any",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": {}
}

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.

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

{
  "type": "object",
  "properties": {
    "verified": {
      "type": "boolean",
      "description": "True only if the recomputed hash matches the on-chain attested hash AND (when a signer was recovered) the signer is the publisher. If false: do NOT act on the data."
    },
    "recomputedHash": {
      "type": "string",
      "description": "keccak256 of the received bytes"
    },
    "onChainHash": {
      "type": "string",
      "description": "The on-chain attested payloadHash compared against"
    },
    "hashMatch": {
      "type": "boolean",
      "description": "Whether the recomputed hash equals the on-chain hash"
    },
    "signer": {
      "description": "Recovered EIP-712 attestation signer (txHash mode)",
      "type": "string"
    },
    "attestingPublisher": {
      "description": "Publisher named in the on-chain event (txHash mode)",
      "type": "string"
    },
    "signerMatch": {
      "description": "Whether the recovered signer is the attesting publisher",
      "type": "boolean"
    },
    "source": {
      "description": "Which anchor was used: 'txHash' or 'expectedHash'",
      "type": "string"
    },
    "txHash": {
      "description": "Settlement tx hash verified against (txHash mode)",
      "type": "string"
    },
    "blockNumber": {
      "description": "Block number of the settlement tx (txHash mode)",
      "type": "string"
    },
    "expired": {
      "description": "Whether the attestation's EIP-712 deadline has passed at check time — the same rule the contract enforces (block.timestamp > deadline). txHash mode only; absent in expectedHash mode, which carries no deadline. NOT folded into `verified`: the chain refuses to emit an already-expired attestation, so every historical settlement reads expired=true as a matter of course, and refusing those would break provenance audits without proving anything. verified answers 'did the publisher sign exactly these bytes'; expired answers 'is that attestation still inside its validity window'. If you need freshness, require verified && !expired.",
      "type": "boolean"
    },
    "deadline": {
      "description": "Attestation deadline as UNIX seconds (decimal string) — txHash mode only",
      "type": "string"
    },
    "checkedAt": {
      "description": "Wall-clock time the expiry comparison was made, UNIX seconds (decimal string)",
      "type": "string"
    },
    "reason": {
      "type": "string",
      "description": "Human-readable verdict an agent can surface when it acts or refuses"
    }
  },
  "required": [
    "verified",
    "recomputedHash",
    "onChainHash",
    "hashMatch",
    "reason"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}