byte-protocol

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['feed'], 'properties': {'body': {'type': 'object', '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, â\x80¦).', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'feed': {'type': 'string', 'minLength': 1, 'description': 'Feed slug â\x80\x94 see https://x402.payperbyte.io/feeds for the live catalog. (For fact-oracle Q&A use byte_query_fact instead â\x80\x94 it uses a different request-response flow.)'}}}

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

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

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

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

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

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

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

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

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

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

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'feeds': {'type': 'array', 'items': {'type': 'object', 'properties': {'topic': {'type': 'string', 'description': 'Topic identifier'}, 'frequency': {'type': 'number', 'description': 'Expected publish cadence in seconds'}, 'publisher': {'type': 'string', 'description': 'Publisher address for the feed'}, 'pricePerKB': {'type': 'string', 'description': 'DEPRECATED (misnamed): identical to pricePerCall â\x80\x94 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.'}, 'pricePerCall': {'type': 'string', 'description': "Per-call price exactly as the gateway catalog reports it â\x80\x94 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."}}, 'additionalProperties': {}}, 'description': 'Catalog of active feeds'}}, 'additionalProperties': False}

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

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

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['subscriber', 'data', 'maxFee'], 'properties': {'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)'}, 'subscriber': {'type': 'string', 'description': 'Subscriber Ethereum address (0x...)'}}}

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

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['question', 'subscriber_address'], 'properties': {'question': {'type': 'string', 'maxLength': 2048, 'minLength': 3, 'description': "The factual question to ask (e.g. 'What was last night's Lakers vs Warriors score?'). Should be specific and verifiable."}, 'topic_filter': {'type': 'string', 'description': "Optional topic filter (e.g. 'fact-oracle' default; future: 'sports', 'finance')."}, 'max_byte_cost': {'type': 'number', 'maximum': 10000, 'minimum': 100, 'description': "Max response payload bytes you're willing to pay for (defaults to 2000). Billed at the publisher's registered price-per-KB â\x80\x94 read it with byte_get_publisher or byte_search_publishers before asking. Publisher refuses if can't fit answer."}, 'min_publisher_pqs': {'type': 'number', 'maximum': 10000, 'minimum': 0, 'description': 'Minimum PQS to consider (BPS scale, 0-10000). 9000 = Elite-only, 7500 = Premium+.'}, '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_response_latency_ms': {'type': 'number', 'maximum': 180000, 'minimum': 5000, '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': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'properties': {'error': {'type': 'string', 'description': 'Error message if the query failed (no eligible publisher, broadcast timeout, etc.)'}, 'answer': {'type': 'string', 'description': "Publisher's grounded answer to the question"}, 'citations': {'type': 'array', 'items': {}, 'description': 'URLs/sources cited by the publisher in support of the answer'}, 'confidence': {'type': 'number', 'description': 'Publisher-reported confidence (0-1)'}, 'elapsed_ms': {'type': 'number', 'description': 'End-to-end time to obtain the answer (ms)'}, 'request_id': {'type': 'string', 'description': 'Request id binding the query to this answer'}, 'payload_hash': {'type': 'string', 'description': 'keccak256 of the response payload'}, 'publisher_pqs': {'type': 'number', 'description': 'Publisher quality score (PQS) at fulfillment'}, 'publisher_address': {'type': 'string', 'description': 'Publisher address that fulfilled the query'}, 'response_size_bytes': {'type': 'number', 'description': 'Size of the response payload (bytes)'}, 'publisher_tx_or_status': {'type': 'string', 'description': 'Delivery status or settlement reference'}}, 'additionalProperties': {}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['stake', 'topic', 'expectedSize', 'maxSize', 'frequency', 'pricePerKB'], 'properties': {'stake': {'type': 'string', 'description': "USDC reputation stake to post, as a decimal string. Default '0' â\x80\x94 PayPerByte v1 publishers are unstaked."}, 'topic': {'type': 'string', 'description': "Data feed topic (e.g. 'eth-price', 'weather-nyc', 'gas-tracker')"}, '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)'}, 'expectedSize': {'type': 'number', 'description': 'Expected payload size in bytes per message'}}}

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

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

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

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['publisher'], 'properties': {'publisher': {'type': 'string', 'description': 'Publisher Ethereum address (0x...) to subscribe to'}, 'skipAllowance': {'type': 'boolean', 'description': "If true, don't bundle the USDC approve(max) call. Default false. Auto-approve is also skipped when the wallet already has â\x89¥ $1000 USDC of allowance to DataStreamLib."}}}

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

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

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

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

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

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['data'], 'properties': {'data': {'type': 'string', 'description': 'The exact payload bytes the agent received and is about to act on â\x80\x94 the raw delivered string, or a 0x-prefixed hex byte string.'}, 'txHash': {'type': 'string', 'pattern': '^0x[0-9a-fA-F]{64}$', '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.'}, 'hashMode': {'enum': ['raw', 'canonical'], 'type': 'string', 'description': "How to hash structured payloads: 'raw' (keccak of the utf8 string, default â\x80\x94 matches byte_publish_data) or 'canonical' (keccak of key-sorted, whitespace-free JSON)."}, 'expectedHash': {'type': 'string', 'pattern': '^0x[0-9a-fA-F]{64}$', 'description': 'On-chain payloadHash to verify against (0x + 64 hex), e.g. the payloadHash returned by byte_query_fact or byte_buy_data.'}}}

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['verified', 'recomputedHash', 'onChainHash', 'hashMatch', 'reason'], 'properties': {'reason': {'type': 'string', 'description': 'Human-readable verdict an agent can surface when it acts or refuses'}, 'signer': {'type': 'string', 'description': 'Recovered EIP-712 attestation signer (txHash mode)'}, 'source': {'type': 'string', 'description': "Which anchor was used: 'txHash' or 'expectedHash'"}, 'txHash': {'type': 'string', 'description': 'Settlement tx hash verified against (txHash mode)'}, 'expired': {'type': 'boolean', 'description': "Whether the attestation's EIP-712 deadline has passed at check time â\x80\x94 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."}, 'deadline': {'type': 'string', 'description': 'Attestation deadline as UNIX seconds (decimal string) â\x80\x94 txHash mode only'}, '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.'}, 'checkedAt': {'type': 'string', 'description': 'Wall-clock time the expiry comparison was made, UNIX seconds (decimal string)'}, 'hashMatch': {'type': 'boolean', 'description': 'Whether the recomputed hash equals the on-chain hash'}, 'blockNumber': {'type': 'string', 'description': 'Block number of the settlement tx (txHash mode)'}, 'onChainHash': {'type': 'string', 'description': 'The on-chain attested payloadHash compared against'}, 'signerMatch': {'type': 'boolean', 'description': 'Whether the recovered signer is the attesting publisher'}, 'recomputedHash': {'type': 'string', 'description': 'keccak256 of the received bytes'}, 'attestingPublisher': {'type': 'string', 'description': 'Publisher named in the on-chain event (txHash mode)'}}, 'additionalProperties': False}