openapi: 3.2.0 info: title: HiveMorph v0.1 X402 API description: 'Polymorphic agent runtime — single shape (Merchant), single supermodel (W2 MERCHANT). Three gates: NEED + YIELD + CLEAN-MONEY.' version: 0.1.0 tags: - name: X402 paths: /v1/x402: get: summary: X402 Facilitator Metadata description: 'HiveMorph x402 facilitator metadata. Lists supported settlement schemes, chain/asset coverage, recipient EOA, and pointer to per-rail discovery.' operationId: x402_facilitator_metadata_v1_x402_get responses: '200': description: Successful Response content: application/json: schema: {} tags: - X402 /v1/x402/pricing: get: tags: - X402 summary: Current x402 pricing table description: 'Returns the full HiveMorph x402 pricing table: all monetized endpoints, their tier assignments, and per-call prices in USD. This endpoint is always free (Tier0).' operationId: get_pricing_v1_x402_pricing_get responses: '200': description: Successful Response content: application/json: schema: {} /v1/x402/stats: get: tags: - X402 summary: x402 call statistics description: 'Returns per-endpoint and aggregate call statistics: total calls served, 402s issued, paid passes, paid revenue, top endpoints. Revenue is real (USDC settled to treasury 0x15184Bf50B3d3F52b60434f8942b7D52F2eB436E on Base 8453). calls_paid=0 indicates no caller has yet completed an end-to-end paid call. This endpoint is always free (Tier0). This endpoint is always free (Tier0).' operationId: get_stats_v1_x402_stats_get responses: '200': description: Successful Response content: application/json: schema: {} /v1/x402/stats/buckets: get: tags: - X402 summary: Bucketed endpoint stats (top-level + drill-down) description: Rolls every per-path counter into ~11 high-level buckets (Receipts, Payments & x402, Discovery & Manifests, Compliance & Audit, Energy & Grid, Identity & Delegation, Morph & Forge, Marketplace & Trade, Vault & Anchor, Affordance & Ops, Other). Each bucket includes its endpoint_count, aggregate counters, and an `endpoints` array for drill-down. Always free (Tier0). operationId: get_stats_buckets_v1_x402_stats_buckets_get responses: '200': description: Successful Response content: application/json: schema: {} /v1/x402/proof/submit: post: tags: - X402 summary: Submit a payment proof description: 'Submit a payment proof for a pending 402 nonce. On success, returns an access token (5-minute TTL) that can be used in the X-Hive-Access header to bypass 402 for the same path. v0.2: REAL on-chain validation — proof_validator.py executes eth_getTransactionReceipt against Base mainnet via JSON-RPC; never fails open on RPC errors. Fake tx_hash returns chain_rejected.' operationId: submit_proof_v1_x402_proof_submit_post requestBody: content: application/json: schema: $ref: '#/components/schemas/ProofSubmitRequest' required: true responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/proof/verify: get: tags: - X402 summary: Verify an access token description: Verify that an access token (issued by proof/submit or X-Payment) is still valid. Access tokens expire after 5 minutes. operationId: verify_token_v1_x402_proof_verify_get parameters: - name: token in: query required: true schema: type: string description: Access token to verify title: Token description: Access token to verify responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/pricing/set: post: tags: - X402 summary: 'Admin: update endpoint pricing' description: 'Set or update the price for a specific path. Requires ADMIN_API_KEY header matching the ADMIN_API_KEY environment variable. If ADMIN_API_KEY is not set, this endpoint returns 403 for all requests. Changes are in-memory only (not persisted across restarts in v0.1).' operationId: set_pricing_v1_x402_pricing_set_post parameters: - name: path in: query required: false schema: anyOf: - type: string - type: 'null' description: URL path to set price for title: Path description: URL path to set price for - name: amount in: query required: false schema: anyOf: - type: number minimum: 0.0 - type: 'null' description: New price in USD title: Amount description: New price in USD - name: X-Admin-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Admin-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PricingSetRequest' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/rails: get: tags: - X402 summary: Available settlement rails description: Returns the list of (chain, asset) rails Hive accepts for x402 settlement, the current default rail, and the on-chain contract / decimals metadata needed by paying agents. Always free. operationId: get_rails_v1_x402_rails_get responses: '200': description: Successful Response content: application/json: schema: {} /v1/x402/rails/select: post: tags: - X402 summary: 'Admin: choose default settlement asset' description: Switch the default settlement asset advertised by `/v1/x402/rails`. Affects only the `default_asset` field exposed to clients — the full `accepts[]` list in 402 responses always includes every active rail. Requires ADMIN_API_KEY header. operationId: select_rail_v1_x402_rails_select_post parameters: - name: X-Admin-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Admin-Api-Key - name: X-Hive-Trust in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Hive-Trust requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RailSelectRequest' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/stats/by-payer: get: tags: - X402 summary: 'Internal: aggregated x402 stats per payer (revenue forensics)' description: Top-100 payer addresses / DIDs by call volume across paid endpoints, with per-endpoint breakdown, status counts, first/last seen, and (when present) referrer DIDs. Gated by HIVE_INTERNAL_DRIVER_KEY via X-Hive-Internal header (RAILS_RULES.md Rule 8). Pure in-memory; no PII beyond payer addr / DID. operationId: stats_by_payer_v1_x402_stats_by_payer_get parameters: - name: path in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter to a single endpoint path. title: Path description: Filter to a single endpoint path. - name: since_minutes in: query required: false schema: anyOf: - type: number minimum: 0 - type: 'null' description: Only events within the last N minutes. title: Since Minutes description: Only events within the last N minutes. responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/today: get: tags: - X402 summary: Today's UTC x402 aggregate (restart-survivable) description: 'Aggregates today''s UTC quote and payment activity from the SQLite persistence layer. Survives Render restarts. Always free (Tier0). Includes barter telemetry: revenue_usd_actual vs revenue_usd_at_asking_equivalent, spread, and accepted_at_floor_pct.' operationId: get_today_v1_x402_today_get parameters: - name: date in: query required: false schema: anyOf: - type: string - type: 'null' description: Optional UTC date in YYYY-MM-DD form. Defaults to today (UTC). title: Date description: Optional UTC date in YYYY-MM-DD form. Defaults to today (UTC). responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/barter: get: tags: - X402 summary: Barter / counter-offer telemetry (per-path + histogram) description: Per-path floor_pct, sample size, conversion-at-floor, total spread, and a demand-curve histogram of paid amounts. Always free (Tier0). This is the observability surface for the counter-offer scheme. operationId: get_barter_v1_x402_barter_get parameters: - name: date in: query required: false schema: anyOf: - type: string - type: 'null' description: Optional UTC date for the histogram. Defaults to today (UTC). title: Date description: Optional UTC date for the histogram. Defaults to today (UTC). - name: bucket_usd in: query required: false schema: type: number exclusiveMinimum: 0 description: Histogram bucket width in USD (default $0.005). default: 0.005 title: Bucket Usd description: Histogram bucket width in USD (default $0.005). responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/failed: get: tags: - X402 summary: Failed-tx recovery queue description: Returns nonces that were quoted but never paid AND nonces whose proof submit failed verification, since `since` (ISO date or unix seconds). Always free (Tier0). operationId: get_failed_v1_x402_failed_get parameters: - name: since in: query required: false schema: anyOf: - type: string - type: 'null' description: ISO timestamp (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ) or unix seconds. Defaults to the start of today (UTC). title: Since description: ISO timestamp (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ) or unix seconds. Defaults to the start of today (UTC). responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/recover: post: tags: - X402 summary: Manually re-verify a previously-failed proof description: Re-submit a (nonce, tx_hash) pair for a previously-failed proof. Useful when an on-chain tx finally confirmed after the nonce briefly tipped into chain_rejected (insufficient confirmations, RPC flake, etc). Re-uses the standard validator path so the same replay/expiry rules apply. operationId: recover_proof_v1_x402_recover_post requestBody: content: application/json: schema: $ref: '#/components/schemas/RecoverRequest' required: true responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/bogo: get: tags: - X402 summary: BOGO (first-call-free) introspection description: 'Returns the BOGO redemption table: how many unique agent_dids have redeemed first-call-free across each endpoint family, plus the list of families covered. Public read — no auth.' operationId: bogo_stats_v1_x402_bogo_get responses: '200': description: Successful Response content: application/json: schema: {} /v1/x402/quote: post: tags: - X402 summary: x402 atomic payment quote — LIVE, USDC on Base 8453 description: 'Produces a signed, machine-redeemable x402 quote for any HiveMorph surface. Real treasury. USDC on Base chain 8453. ERC-681 deeplink ready for any wallet or agent. Includes a service-signed receipt envelope verifiable against /v1/receipt/verify and /v1/prov/pubkey, plus a crypto_agility block declaring classical (Ed25519) and post-quantum-ready (ML-KEM/ML-DSA) posture. Receipt-profile gating: ''pq'' requires a valid regulated-tier delegation envelope (regulated_envelope_jti). Otherwise the call returns 402 regulated_tier_required.' operationId: quote_v1_x402_quote_post requestBody: content: application/json: schema: $ref: '#/components/schemas/QuoteRequest' required: true responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/client-intent: get: tags: - X402 summary: Browser/wallet-consumable x402 payment intent (LIVE nonce) description: 'Returns the safe, browser-consumable fields from a live x402 payment envelope: amount, asset, chain, contract, recipient, decimals, nonce, expires_at, payment_endpoint, per-chain ERC-681 deeplink, and the exact proof-submission shape. Registers a REAL redeemable nonce. profile=nano|standard (pq needs a regulated delegation envelope — use POST /v1/x402/quote for pq). Wallet-native one-click pay is supported up to the final client broadcast+proof step, which the wallet performs.' operationId: client_intent_get_v1_x402_client_intent_get parameters: - name: profile in: query required: false schema: type: string description: 'Receipt profile: nano | standard.' default: nano title: Profile description: 'Receipt profile: nano | standard.' - name: amount_usdc in: query required: false schema: anyOf: - type: number maximum: 10000000.0 minimum: 0.0001 - type: 'null' description: Explicit USDC amount. Overrides the profile default price. title: Amount Usdc description: Explicit USDC amount. Overrides the profile default price. - name: endpoint_path in: query required: false schema: anyOf: - type: string maxLength: 512 - type: 'null' description: Optional target path to price the intent for (pricing-table lookup). title: Endpoint Path description: Optional target path to price the intent for (pricing-table lookup). responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - X402 summary: Browser/wallet-consumable x402 payment intent (LIVE nonce) — POST operationId: client_intent_post_v1_x402_client_intent_post requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/ClientIntentRequest' - type: 'null' title: Body responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/x402/wallet-intent: get: tags: - X402 summary: Alias of GET /v1/x402/client-intent operationId: wallet_intent_get_v1_x402_wallet_intent_get parameters: - name: profile in: query required: false schema: type: string default: nano title: Profile - name: amount_usdc in: query required: false schema: anyOf: - type: number maximum: 10000000.0 minimum: 0.0001 - type: 'null' title: Amount Usdc - name: endpoint_path in: query required: false schema: anyOf: - type: string maxLength: 512 - type: 'null' title: Endpoint Path responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - X402 summary: Alias of POST /v1/x402/client-intent operationId: wallet_intent_post_v1_x402_wallet_intent_post requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/ClientIntentRequest' - type: 'null' title: Body responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError RailSelectRequest: properties: asset: type: string title: Asset description: Default settlement asset to advertise. 'USDC' or 'USDT'. type: object required: - asset title: RailSelectRequest description: Body for POST /v1/x402/rails/select. PricingSetRequest: properties: path: anyOf: - type: string - type: 'null' title: Path description: URL path to set price for. amount: anyOf: - type: number minimum: 0.0 - type: 'null' title: Amount description: New price in USD. tier: anyOf: - type: string - type: 'null' title: Tier description: Tier label (optional; inferred from amount if omitted). description: anyOf: - type: string - type: 'null' title: Description description: Human-readable note. asset: anyOf: - type: string - type: 'null' title: Asset description: Optional asset filter. If provided ('USDC' or 'USDT'), updates the per-asset price for this path only — the cross-asset base price is unchanged. Useful when Tether/Circle peg spreads diverge. type: object title: PricingSetRequest description: Body for POST /v1/x402/pricing/set (also accepts query params). ClientIntentRequest: properties: profile: type: string maxLength: 16 title: Profile description: nano | standard. default: nano amount_usdc: anyOf: - type: number maximum: 10000000.0 minimum: 0.0001 - type: 'null' title: Amount Usdc endpoint_path: anyOf: - type: string maxLength: 512 - type: 'null' title: Endpoint Path type: object title: ClientIntentRequest description: Optional body for POST /v1/x402/client-intent (and wallet-intent alias). RecoverRequest: properties: nonce: type: string title: Nonce description: Nonce of a previously failed proof. tx_hash: type: string title: Tx Hash description: On-chain tx hash to re-verify. payer: type: string title: Payer description: Payer address (optional; carried for audit). default: '' chain: type: string title: Chain description: '''base'', ''ethereum'', or ''solana''.' default: base asset: type: string title: Asset description: Asset of the original quote. default: USDC type: object required: - nonce - tx_hash title: RecoverRequest description: Body for POST /v1/x402/recover. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ProofSubmitRequest: properties: nonce: type: string title: Nonce description: Nonce from the 402 PaymentRequired response. payer: type: string title: Payer description: On-chain address of the paying account. chain: type: string title: Chain description: '''base'' or ''solana''.' tx_hash: type: string title: Tx Hash description: On-chain transaction hash (Base) or signature (Solana). Validated against the chain via JSON-RPC — see proof_validator.py. Fake or unfound tx_hash returns chain_rejected; never fails open. amount_usd: type: number title: Amount Usd description: Claimed payment amount (informational). default: 0.0 asset: type: string title: Asset description: Payment asset. 'USDC' or 'USDPT'. default: USDC type: object required: - nonce - payer - chain - tx_hash title: ProofSubmitRequest description: Body for POST /v1/x402/proof/submit. QuoteRequest: properties: endpoint_path: anyOf: - type: string maxLength: 512 - type: 'null' title: Endpoint Path description: Optional HiveMorph endpoint path the caller intends to redeem the quote for (e.g. '/v1/receipt/emit'). Used to look up the price from the x402 pricing table. Mutually exclusive with amount_usdc; if both are supplied, amount_usdc wins. amount_usdc: anyOf: - type: number maximum: 10000000.0 minimum: 0.0001 - type: 'null' title: Amount Usdc description: Optional explicit USDC amount. Overrides endpoint_path lookup. receipt_profile: type: string maxLength: 16 title: Receipt Profile description: 'Receipt profile attached to the quote: nano | standard | pq.' default: standard agent_did: anyOf: - type: string maxLength: 200 - type: 'null' title: Agent Did description: Caller agent DID. Surfaced in the receipt and audit row. counterparty_did: anyOf: - type: string maxLength: 200 - type: 'null' title: Counterparty Did description: Optional payee/counterparty DID for two-sided settlement. hktn_tier: anyOf: - type: string maxLength: 24 - type: 'null' title: Hktn Tier description: Optional explicit HKTN reputation tier override (cold|warm|hot|regulated, or legacy bronze|silver|gold|platinum|pq_eligible). When omitted, the tier is resolved from agent_did via the R5 ledger; if neither is supplied, default is Cold. memo: type: string maxLength: 64 title: Memo description: Optional short memo (≤ 64 chars). Included in the quote payload and receipt hash. Not embedded in the ERC-681 deeplink — ERC-681 transfer URIs do not carry memos. default: '' regulated_envelope_jti: anyOf: - type: string maxLength: 64 - type: 'null' title: Regulated Envelope Jti description: Required when receipt_profile='pq'. The jti of a delegation envelope (issued via /v1/delegation/issue or /operator-sign) whose allowed_surfaces includes 'pq'. Caller asserts authority; this endpoint verifies it on-the-fly. type: object title: QuoteRequest description: 'Body for POST /v1/x402/quote. All fields optional — caller can ask for a generic settlement quote, or a quote tied to a specific HiveMorph endpoint, or a quote for a specific USDC amount. Receipt profile defaults to ''standard''.'