{"openapi":"3.1.0","info":{"title":"x402 Stacks Sponsor Relay","version":"1.33.2","description":"A Cloudflare Worker enabling gasless transactions for AI agents on the Stacks blockchain. Accepts pre-signed sponsored transactions, sponsors them, and performs native settlement verification directly."},"tags":[{"name":"Health","description":"Service health endpoints"},{"name":"Relay","description":"Transaction relay endpoints (native settlement)"},{"name":"Sponsor","description":"Transaction sponsor endpoints (direct broadcast)"},{"name":"Verify","description":"Payment receipt verification"},{"name":"Access","description":"Protected resource access"},{"name":"Provision","description":"API key provisioning via Bitcoin signature"},{"name":"Fees","description":"Fee estimation endpoints"},{"name":"Dashboard","description":"Public statistics endpoints"},{"name":"Nonce","description":"Nonce coordinator diagnostics"},{"name":"x402 V2","description":"x402 V2 facilitator API (spec-compliant)"},{"name":"Wallets","description":"Sponsor wallet monitoring (balance, fees, pool state)"}],"servers":[{"url":"https://x402-relay.aibtc.dev","description":"Staging (testnet)"},{"url":"https://x402-relay.aibtc.com","description":"Production (mainnet)"}],"components":{"schemas":{},"parameters":{}},"paths":{"/health":{"get":{"tags":["Health"],"summary":"Service health summary","description":"Returns the relay service health summary with network and version. Use GET /status/sponsor for sponsor readiness and GET /wallets for operator wallet details.","operationId":"get_Health","responses":{"200":{"description":"Service health status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking"},"status":{"type":"string","enum":["ok","degraded"],"description":"'ok' when the nonce pool is healthy, 'degraded' when the pool reports unhealthy (circuit breaker open, gaps detected, or low capacity). Consumers should treat any non-'ok' value as unhealthy.","example":"ok"},"network":{"type":"string","example":"testnet"},"version":{"type":"string","example":"1.33.2"}}}}}}}}},"/status/sponsor":{"get":{"tags":["Health"],"summary":"Cached sponsor readiness snapshot","description":"Returns the relay-owned cached sponsor readiness snapshot. Reads never fan out to Hiro on the request path.","operationId":"get_SponsorStatus","responses":{"200":{"description":"Fresh or stale sponsor status snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking"},"status":{"type":"string","enum":["healthy","degraded"]},"canSponsor":{"type":"boolean"},"walletCount":{"type":"number"},"recommendation":{"type":"string","nullable":true,"enum":["fallback_to_direct"]},"reasons":{"type":"array","items":{"type":"string","enum":["NO_AVAILABLE_NONCES","ALL_WALLETS_DEGRADED","RECENT_CONFLICT","HEAL_IN_PROGRESS","RECONCILIATION_STALE","SNAPSHOT_STALE"]}},"noncePool":{"type":"object","properties":{"totalAvailable":{"type":"number"},"totalReserved":{"type":"number"},"totalCapacity":{"type":"number"},"poolAvailabilityRatio":{"type":"number"},"conflictsDetected":{"type":"number"},"lastConflictAt":{"type":"string","nullable":true},"healInProgress":{"type":"boolean"}}},"reconciliation":{"type":"object","properties":{"source":{"type":"string","enum":["hiro"]},"lastSuccessfulAt":{"type":"string","nullable":true},"freshness":{"type":"string","enum":["fresh","stale","unavailable"]}}},"snapshot":{"type":"object","properties":{"asOf":{"type":"string"},"ageMs":{"type":"number"},"freshness":{"type":"string","enum":["fresh","stale","expired"]}}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"503":{"description":"Expired sponsor status snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking"},"status":{"type":"string","enum":["unavailable"]},"canSponsor":{"type":"boolean"},"walletCount":{"type":"number"},"recommendation":{"type":"string","nullable":true,"enum":["fallback_to_direct"]},"reasons":{"type":"array","items":{"type":"string","enum":["NO_AVAILABLE_NONCES","ALL_WALLETS_DEGRADED","RECENT_CONFLICT","HEAL_IN_PROGRESS","RECONCILIATION_STALE","SNAPSHOT_STALE"]}},"noncePool":{"type":"object","properties":{"totalAvailable":{"type":"number"},"totalReserved":{"type":"number"},"totalCapacity":{"type":"number"},"poolAvailabilityRatio":{"type":"number"},"conflictsDetected":{"type":"number"},"lastConflictAt":{"type":"string","nullable":true},"healInProgress":{"type":"boolean"}}},"reconciliation":{"type":"object","properties":{"source":{"type":"string","enum":["hiro"]},"lastSuccessfulAt":{"type":"string","nullable":true},"freshness":{"type":"string","enum":["fresh","stale","unavailable"]}}},"snapshot":{"type":"object","properties":{"asOf":{"type":"string"},"ageMs":{"type":"number"},"freshness":{"type":"string","enum":["expired"]}}}}}}}}}}},"/relay":{"post":{"tags":["Relay"],"summary":"Submit sponsored transaction for settlement","description":"Accepts a pre-signed sponsored transaction, sponsors it with the relay's key, verifies payment locally, and broadcasts directly to the Stacks network.","operationId":"post_Relay","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["transaction","settle"],"properties":{"transaction":{"type":"string","description":"Hex-encoded signed sponsored transaction","example":"0x00000001..."},"settle":{"type":"object","required":["expectedRecipient","minAmount"],"properties":{"expectedRecipient":{"type":"string","description":"Expected recipient address","example":"SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"},"minAmount":{"type":"string","description":"Minimum amount required (in smallest unit - microSTX, sats, etc.)","example":"1000000"},"tokenType":{"type":"string","enum":["STX","sBTC","USDCx"],"default":"STX","description":"Token type for payment"},"expectedSender":{"type":"string","description":"Expected sender address (optional)"},"resource":{"type":"string","description":"API resource being accessed (optional)"},"method":{"type":"string","description":"HTTP method being used (optional)"},"maxTimeoutSeconds":{"type":"number","description":"Maximum timeout in seconds for settlement polling (optional, caps broadcastAndConfirm; default 60s)","example":30}}},"auth":{"type":"object","description":"Optional SIP-018 structured data signature for authentication","properties":{"signature":{"type":"string","description":"RSV signature of the structured data","example":"0x1234..."},"message":{"type":"object","required":["action","nonce","expiry"],"properties":{"action":{"type":"string","description":"Action being performed (should be 'relay')","example":"relay"},"nonce":{"type":"string","description":"Unix timestamp ms for replay protection","example":"1708099200000"},"expiry":{"type":"string","description":"Expiry timestamp (unix ms) for time-bound authorization","example":"1708185600000"}}}}}}}}}},"responses":{"200":{"description":"Transaction sponsored and settled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking","example":"550e8400-e29b-41d4-a716-446655440000"},"txid":{"type":"string","description":"Transaction ID","example":"0x1234..."},"explorerUrl":{"type":"string","description":"Link to view transaction on Hiro Explorer","example":"https://explorer.hiro.so/txid/0x1234...?chain=testnet"},"settlement":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string","enum":["pending","confirmed","failed"]},"sender":{"type":"string","description":"Sender Stacks address (c32check-encoded, human-readable)"},"recipient":{"type":"string"},"amount":{"type":"string"},"blockHeight":{"type":"number"}}},"sponsoredTx":{"type":"string","description":"Hex-encoded fully-sponsored transaction (can be used as X-PAYMENT header value)","example":"0x00000001..."},"receiptId":{"type":"string","format":"uuid","description":"Receipt token for verifying payment via GET /verify/:receiptId","example":"550e8400-e29b-41d4-a716-446655440000"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"401":{"description":"Authentication failed (invalid or expired SIP-018 signature)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"409":{"description":"Nonce conflict — resubmit with a new transaction","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"502":{"description":"Broadcast or network error","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}},"503":{"description":"Nonce coordinator unavailable — retry after delay","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}}}}},"/sponsor":{"post":{"tags":["Sponsor"],"summary":"Sponsor and broadcast a transaction","description":"Accepts a pre-signed sponsored transaction, adds the sponsor signature, and broadcasts directly to the Stacks network. Unlike /relay, this does NOT perform settlement verification. Requires API key authentication.","security":[{"bearerAuth":[]}],"operationId":"post_Sponsor","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["transaction"],"properties":{"transaction":{"type":"string","description":"Hex-encoded signed sponsored transaction","example":"0x00000001..."},"auth":{"type":"object","description":"Optional SIP-018 structured data signature for authentication","properties":{"signature":{"type":"string","description":"RSV signature of the structured data","example":"0x1234..."},"message":{"type":"object","required":["action","nonce","expiry"],"properties":{"action":{"type":"string","description":"Action being performed (should be 'sponsor')","example":"sponsor"},"nonce":{"type":"string","description":"Unix timestamp ms for replay protection","example":"1708099200000"},"expiry":{"type":"string","description":"Expiry timestamp (unix ms) for time-bound authorization","example":"1708185600000"}}}}}}}}}},"responses":{"200":{"description":"Transaction sponsored and broadcast successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking","example":"550e8400-e29b-41d4-a716-446655440000"},"txid":{"type":"string","description":"Transaction ID","example":"0x1234..."},"explorerUrl":{"type":"string","description":"Link to view transaction on Hiro Explorer","example":"https://explorer.hiro.so/txid/0x1234...?chain=testnet"},"fee":{"type":"string","description":"Fee paid by sponsor in microSTX","example":"1000"},"nonceExpiresAt":{"type":"string","format":"date-time","description":"ISO 8601 UTC timestamp after which the relay may reclaim this sponsor nonce. Callers MUST NOT retry the same sponsored hex past this timestamp — re-call /sponsor with the same inner client-signed payload to mint a fresh sponsorship instead.","example":"2026-05-18T12:10:00.000Z"},"sponsorNonceValidForMs":{"type":"integer","description":"Duration in milliseconds for which this sponsor nonce is valid, equal to the relay's STALE_THRESHOLD_MS constant (600000 = 10 minutes). Use this to derive a relative retry budget without parsing the absolute timestamp.","example":600000}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"409":{"description":"Nonce conflict — resubmit with a new transaction","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"429":{"description":"Spending cap exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"502":{"description":"Broadcast failed","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}},"503":{"description":"Nonce coordinator unavailable — retry after delay","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}}}}},"/verify/{receiptId}":{"get":{"tags":["Verify"],"summary":"Verify a payment receipt","description":"Look up a payment receipt by ID and return its status. Receipts are created when a transaction is successfully settled via POST /relay. The receiptId is passed as a URL path parameter.","operationId":"get_Verify","responses":{"200":{"description":"Receipt found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid"},"receipt":{"type":"object","properties":{"receiptId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["valid","consumed"],"description":"Receipt status"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"senderAddress":{"type":"string","description":"Agent's Stacks address"},"txid":{"type":"string","description":"Transaction ID"},"explorerUrl":{"type":"string"},"settlement":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string"},"recipient":{"type":"string"},"amount":{"type":"string"}}},"resource":{"type":"string","description":"Requested resource"},"method":{"type":"string","description":"HTTP method"},"accessCount":{"type":"number","description":"Number of times this receipt has been used"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/access":{"post":{"tags":["Access"],"summary":"Access protected resource with receipt","description":"Present a payment receipt to access a protected resource. The relay validates the receipt (exists, not expired/consumed, resource matches) and either returns data directly or proxies to a downstream service with the sponsored tx hex as X-Payment header. Marks receipt as consumed after successful access.","operationId":"post_Access","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"receiptId":{"type":"string","format":"uuid","description":"Receipt ID from a successful relay transaction"},"resource":{"type":"string","description":"Resource path being accessed (must match receipt)"},"targetUrl":{"type":"string","format":"uri","description":"Optional downstream service URL for proxying"}},"required":["receiptId"]}}}},"responses":{"200":{"description":"Access granted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid"},"granted":{"type":"boolean","example":true},"receipt":{"type":"object","properties":{"receiptId":{"type":"string"},"senderAddress":{"type":"string"},"resource":{"type":"string"},"accessCount":{"type":"number"}}},"data":{"type":"object","description":"Resource data (if relay-hosted)"},"proxy":{"type":"object","description":"Proxy response (if targetUrl provided)","properties":{"status":{"type":"number"},"statusText":{"type":"string"},"headers":{"type":"object"},"body":{"type":"object"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"502":{"description":"Broadcast or settlement error","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}}}}},"/keys/provision":{"post":{"tags":["Provision"],"summary":"Provision an API key via Bitcoin signature","description":"Self-provision a free-tier API key by proving Bitcoin address ownership via BIP-137 or BIP-322 signature verification. All Bitcoin address formats are supported: P2PKH (1...) and P2SH (3...) use BIP-137; native SegWit (bc1q...) and Taproot (bc1p...) use BIP-322 'simple' format. Supports two paths: Registration (bare message 'Bitcoin will be the currency of AIs') and Self-service (message with timestamp within 5 minutes). Returns HTTP 409 if BTC address already has a provisioned key.","operationId":"post_Provision","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["btcAddress","signature","message"],"properties":{"btcAddress":{"type":"string","description":"Bitcoin address used to sign the message. All formats supported: P2PKH (1...) and P2SH (3...) use BIP-137 signatures; native SegWit (bc1q...) uses BIP-322 ECDSA signatures; Taproot (bc1p...) uses BIP-322 Schnorr signatures. For Stacks addresses, use POST /keys/provision-stx instead.","example":"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"},"signature":{"type":"string","description":"Base64-encoded BIP-137 or BIP-322 signature of the message. P2PKH/P2SH wallets produce BIP-137 (65 bytes). P2WPKH/P2TR wallets produce BIP-322 'simple' witness-serialized format.","example":"H9L5yLFjti0QTHhPyFrZCT1V/MMnBtXKmoiKDZ78NDBjERki6ZTQZdSMCtkgoNmp17By9ItJr8o7ChX0XxY91nk="},"message":{"type":"string","description":"Message that was signed. Either bare message 'Bitcoin will be the currency of AIs' (registration path) or message with timestamp 'Bitcoin will be the currency of AIs | {ISO-timestamp}' (self-service path, must be within 5 minutes)","example":"Bitcoin will be the currency of AIs | 2026-02-12T12:00:00.000Z"}}}}}},"responses":{"200":{"description":"API key provisioned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking","example":"550e8400-e29b-41d4-a716-446655440000"},"apiKey":{"type":"string","description":"The generated API key (only shown once, store securely)","example":"x402_sk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"},"metadata":{"type":"object","properties":{"keyId":{"type":"string","example":"a1b2c3d4"},"appName":{"type":"string","example":"btc:1A1zP1eP"},"contactEmail":{"type":"string","example":"btc+1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa@x402relay.system"},"tier":{"type":"string","enum":["free"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"active":{"type":"boolean","example":true},"btcAddress":{"type":"string","example":"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"409":{"description":"Resource already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/keys/provision-stx":{"post":{"tags":["Provision"],"summary":"Provision an API key via Stacks signature","description":"Self-provision a free-tier API key by proving Stacks address ownership via message signature verification. Supports two paths: Registration (bare message 'Bitcoin will be the currency of AIs') and Self-service (message with timestamp within 5 minutes). Returns HTTP 409 if Stacks address already has a provisioned key.","operationId":"post_ProvisionStx","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stxAddress","signature","message"],"properties":{"stxAddress":{"type":"string","description":"Stacks address used to sign the message (mainnet: SP..., testnet: ST...)","example":"SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7"},"signature":{"type":"string","description":"RSV signature of the message (hex-encoded)","example":"0x01234567890abcdef..."},"message":{"type":"string","description":"Message that was signed. Either bare message 'Bitcoin will be the currency of AIs' (registration path) or message with timestamp 'Bitcoin will be the currency of AIs | {ISO-timestamp}' (self-service path, must be within 5 minutes)","example":"Bitcoin will be the currency of AIs | 2026-02-16T12:00:00.000Z"}}}}}},"responses":{"200":{"description":"API key provisioned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking","example":"550e8400-e29b-41d4-a716-446655440000"},"apiKey":{"type":"string","description":"The generated API key (only shown once, store securely)","example":"x402_sk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"},"metadata":{"type":"object","properties":{"keyId":{"type":"string","example":"a1b2c3d4"},"appName":{"type":"string","example":"stx:SP2J6ZY4"},"contactEmail":{"type":"string","example":"stx+SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7@x402relay.system"},"tier":{"type":"string","enum":["free"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"active":{"type":"boolean","example":true},"stxAddress":{"type":"string","example":"SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"409":{"description":"Resource already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/fees":{"get":{"tags":["Fees"],"summary":"Get clamped fee estimates","description":"Returns fee estimates for all transaction types (token_transfer, contract_call, smart_contract) with per-type floor/ceiling clamps applied. Fetches from Hiro API with 60s KV caching. Prevents overpayment from mempool poisoning by capping maximum fees.","operationId":"get_Fees","responses":{"200":{"description":"Fee estimates retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking"},"fees":{"type":"object","description":"Clamped fee estimates in microSTX","properties":{"token_transfer":{"type":"object","properties":{"low_priority":{"type":"number","example":180},"medium_priority":{"type":"number","example":180},"high_priority":{"type":"number","example":180}}},"contract_call":{"type":"object","properties":{"low_priority":{"type":"number","example":3000},"medium_priority":{"type":"number","example":50000},"high_priority":{"type":"number","example":50000}}},"smart_contract":{"type":"object","properties":{"low_priority":{"type":"number","example":10000},"medium_priority":{"type":"number","example":40000},"high_priority":{"type":"number","example":40000}}}}},"source":{"type":"string","enum":["hiro","cache","default"],"description":"Source of fee data (hiro=fresh, cache=cached, default=fallback)"},"cached":{"type":"boolean","description":"Whether this data came from cache"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/fees/config":{"post":{"tags":["Fees"],"summary":"Update fee clamp configuration","description":"Update the floor and ceiling values for fee clamping. Requires API key authentication. Changes take effect immediately via KV storage.","security":[{"bearerAuth":[]}],"operationId":"post_FeesConfig","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token_transfer":{"type":"object","properties":{"floor":{"type":"number","description":"Minimum fee in microSTX","example":180},"ceiling":{"type":"number","description":"Maximum fee in microSTX","example":3000}}},"contract_call":{"type":"object","properties":{"floor":{"type":"number","description":"Minimum fee in microSTX","example":3000},"ceiling":{"type":"number","description":"Maximum fee in microSTX","example":50000}}},"smart_contract":{"type":"object","properties":{"floor":{"type":"number","description":"Minimum fee in microSTX","example":10000},"ceiling":{"type":"number","description":"Maximum fee in microSTX","example":50000}}}},"description":"Partial update: only provided transaction types will be updated. Omit a type to keep its current values."}}}},"responses":{"200":{"description":"Configuration updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking","example":"550e8400-e29b-41d4-a716-446655440000"},"config":{"type":"object","description":"Updated clamp configuration","properties":{"token_transfer":{"type":"object","properties":{"floor":{"type":"number"},"ceiling":{"type":"number"}}},"contract_call":{"type":"object","properties":{"floor":{"type":"number"},"ceiling":{"type":"number"}}},"smart_contract":{"type":"object","properties":{"floor":{"type":"number"},"ceiling":{"type":"number"}}}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/stats":{"get":{"tags":["Dashboard"],"summary":"Get relay statistics","description":"Returns aggregated statistics about relay transactions, token breakdown, and settlement health. This is a public endpoint.","operationId":"get_DashboardStats","responses":{"200":{"description":"Statistics retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking"},"period":{"type":"string","enum":["24h","7d"],"description":"Time period for the stats"},"transactions":{"type":"object","properties":{"total":{"type":"number"},"success":{"type":"number"},"failed":{"type":"number"},"clientErrors":{"type":"number","description":"Number of failures caused by client errors (bad params, nonce conflicts, rate limits). Excluded from effective success rate calculation."},"trend":{"type":"string","enum":["up","down","stable"]},"previousTotal":{"type":"number","description":"Total transactions in the previous rolling 24h window (24-48h ago) for trend comparison."},"rawSuccessRate":{"type":"number","description":"Raw success rate = success / total. Includes client errors in denominator. Range 0-1."},"effectiveSuccessRate":{"type":"number","description":"Effective success rate = success / (success + relayErrors). Excludes client errors from denominator. Range 0-1."}}},"tokens":{"type":"object","properties":{"STX":{"type":"object","properties":{"count":{"type":"number"},"volume":{"type":"string"},"percentage":{"type":"number"}}},"sBTC":{"type":"object","properties":{"count":{"type":"number"},"volume":{"type":"string"},"percentage":{"type":"number"}}},"USDCx":{"type":"object","properties":{"count":{"type":"number"},"volume":{"type":"string"},"percentage":{"type":"number"}}}}},"settlement":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","down","unknown"]},"avgLatencyMs":{"type":"number"},"uptime24h":{"type":"number"},"lastCheck":{"type":"string","nullable":true,"format":"date-time"}}},"hourlyData":{"type":"array","items":{"type":"object","properties":{"hour":{"type":"string"},"transactions":{"type":"number"},"success":{"type":"number"}}}},"apiKeys":{"type":"object","nullable":true,"description":"API key aggregate statistics (only present if API_KEYS_KV is configured)","properties":{"totalActiveKeys":{"type":"number","description":"Total number of active API keys"},"totalFeesToday":{"type":"string","description":"Total fees sponsored today in microSTX"},"topKeys":{"type":"array","description":"Top keys by request count (max 5)","items":{"type":"object","properties":{"keyPrefix":{"type":"string","description":"First 12 characters of keyId for anonymization"},"requestsToday":{"type":"number","description":"Number of requests made today"},"feesToday":{"type":"string","description":"Total fees sponsored today in microSTX"},"status":{"type":"string","enum":["active","rate_limited","capped"],"description":"Current status of the key"}}}}}},"terminalReasons":{"type":"object","nullable":true,"description":"Error counts grouped by tx-schemas terminal reason category (today's calendar-day). Additive alongside legacy errors object. Categories: validation, sender, relay, settlement, replacement, identity.","properties":{"validation":{"type":"number","description":"invalid_transaction, not_sponsored"},"sender":{"type":"number","description":"sender_nonce_* errors, origin_chaining_limit, sender_hand_expired"},"relay":{"type":"number","description":"sponsor_failure, queue_unavailable, internal_error, sponsor_exhausted, sponsor_nonce_conflict"},"settlement":{"type":"number","description":"broadcast_failure, chain_abort, broadcast_rate_limited"},"replacement":{"type":"number","description":"nonce_replacement, superseded"},"identity":{"type":"number","description":"expired, unknown_payment_identity"}}},"walletThroughput":{"type":"array","nullable":true,"description":"Per-wallet 24h throughput totals with hourly spark data. Only includes wallets with at least one transaction in the last 24h.","items":{"type":"object","properties":{"walletIndex":{"type":"number","description":"Sponsor wallet index (0-based)"},"total24h":{"type":"number","description":"Total transactions in rolling 24h"},"success24h":{"type":"number","description":"Successful transactions in rolling 24h"},"failed24h":{"type":"number","description":"Failed transactions in rolling 24h"},"feeTotal24h":{"type":"string","description":"Total fees paid by this wallet in microSTX (rolling 24h)"},"hourly":{"type":"array","description":"Hourly spark data for the last 24h","items":{"type":"object","properties":{"hour":{"type":"string"},"total":{"type":"number"},"success":{"type":"number"},"failed":{"type":"number"},"feeTotal":{"type":"string"}}}}}}},"previous24h":{"type":"object","nullable":true,"description":"Rolling 24h totals from the previous window (24-48h ago). Used for rolling-vs-rolling trend comparison.","properties":{"total":{"type":"number"},"success":{"type":"number"},"failed":{"type":"number"}}},"endpointBreakdown":{"type":"object","nullable":true,"description":"Per-endpoint transaction breakdown (today's calendar-day counters from StatsDO). Only present when StatsDO is configured.","properties":{"relay":{"type":"object","description":"Stats for POST /relay (sponsored transactions with settlement)","properties":{"total":{"type":"number"},"success":{"type":"number"},"failed":{"type":"number"}}},"sponsor":{"type":"object","description":"Stats for POST /sponsor (direct sponsoring, API key required)","properties":{"total":{"type":"number"},"success":{"type":"number"},"failed":{"type":"number"}}},"settle":{"type":"object","description":"Stats for POST /settle (x402 V2 facilitator — no sponsoring)","properties":{"total":{"type":"number"},"success":{"type":"number"},"failed":{"type":"number"},"clientErrors":{"type":"number","description":"Settle failures caused by client errors (invalid payload, wrong recipient, etc.)"}}},"verify":{"type":"object","description":"Stats for POST /verify (x402 V2 local validation only)","properties":{"total":{"type":"number"}}}}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/stats/transactions":{"get":{"tags":["Dashboard"],"summary":"Get recent transaction log","description":"Returns individual transaction records (newest-first). Query params: days (1-7, default 1), limit (1-200, default 50), endpoint (relay|sponsor|settle).","operationId":"get_TransactionLog","responses":{"200":{"description":"Transaction log retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid"},"count":{"type":"number","description":"Number of entries returned"},"transactions":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"endpoint":{"type":"string","enum":["relay","sponsor","settle"]},"success":{"type":"boolean"},"tokenType":{"type":"string","enum":["STX","sBTC","USDCx"]},"amount":{"type":"string"},"fee":{"type":"string"},"txid":{"type":"string"},"sender":{"type":"string"},"recipient":{"type":"string"},"status":{"type":"string","enum":["confirmed","pending","failed"]},"blockHeight":{"type":"number"}}}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/nonce/stats":{"get":{"tags":["Nonce"],"summary":"Get nonce coordinator stats","description":"Returns nonce assignment and txid tracking statistics from the Nonce Durable Object. Includes gap recovery counters and a derived gapStatus summary.","operationId":"get_NonceStatsEndpoint","responses":{"200":{"description":"Nonce stats retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking"},"stats":{"type":"object","properties":{"totalAssigned":{"type":"number"},"conflictsDetected":{"type":"number"},"lastAssignedNonce":{"type":"number","nullable":true},"lastAssignedAt":{"type":"string","nullable":true},"nextNonce":{"type":"number","nullable":true},"txidCount":{"type":"number"},"gapsRecovered":{"type":"number","description":"Number of times the alarm or on-demand resync recovered from a nonce gap"},"lastHiroSync":{"type":"string","nullable":true,"description":"ISO timestamp of last successful Hiro nonce sync"},"lastGapDetected":{"type":"string","nullable":true,"description":"ISO timestamp of last gap detection"},"gapStatus":{"type":"string","enum":["recent_gap","gaps_recovered_historically","no_gaps"],"description":"Derived gap health summary. 'recent_gap' = gap detected within the last 10 minutes; 'gaps_recovered_historically' = at least one gap was recovered but not recently; 'no_gaps' = no gap ever detected."}}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/nonce/state":{"get":{"tags":["Nonce"],"summary":"Observable nonce state for client diagnostics","description":"Returns the relay's internal nonce state per wallet — pending transactions, detected gaps, circuit breaker status, and heal progress. Designed for MCP tools like `tx_status_deep` to cross-reference sender nonces with sponsor nonces without scraping the Hiro mempool API.","operationId":"get_NonceState","responses":{"200":{"description":"Nonce state retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid"},"state":{"type":"object","properties":{"wallets":{"type":"array","items":{"type":"object","properties":{"walletIndex":{"type":"number"},"sponsorAddress":{"type":"string"},"chainFrontier":{"type":"number","description":"Next expected nonce on-chain (Hiro possible_next_nonce, monotonic high-water mark)"},"assignmentHead":{"type":"number","description":"Next nonce the relay will assign (one past the highest assigned/broadcasted)"},"pendingTxs":{"type":"array","items":{"type":"object","properties":{"sponsorNonce":{"type":"number"},"state":{"type":"string","enum":["assigned","broadcasted","replaced"]},"txid":{"type":"string"},"assignedAt":{"type":"string"},"broadcastedAt":{"type":"string"},"senderAddress":{"type":"string","description":"Stacks address of the transaction sender (from dispatch_queue, absent if not yet dispatched)"},"originalTxid":{"type":"string","description":"Original sponsored txid that was replaced (present when state is 'replaced')"},"replacementTxid":{"type":"string","description":"Txid of the relay's replacement transaction, if the relay performed the RBF (present when state is 'replaced' via head-bump/RBF)"},"replacedReason":{"type":"string","description":"Contention reason string, e.g. 'contention:dropped_replace_by_fee' (present when state is 'replaced')"}}}},"gaps":{"type":"array","items":{"type":"number"},"description":"Missing nonce values between chain frontier and assignment head"},"available":{"type":"number","description":"Effective headroom — how many more nonces this wallet can accept (same calc as assignment)"},"reserved":{"type":"number","description":"In-flight nonces across all states (assigned + broadcasted + confirmed-pending)"},"circuitBreakerOpen":{"type":"boolean"},"healthy":{"type":"boolean"},"settlementTimes":{"type":"object","description":"Per-wallet broadcast-to-confirmation latency percentiles (last 24h)","properties":{"p50":{"type":"number","description":"Median settlement time in milliseconds"},"p95":{"type":"number","description":"95th percentile settlement time in milliseconds"},"avg":{"type":"number","description":"Average settlement time in milliseconds"},"count":{"type":"number","description":"Number of confirmed transactions in the sample"}}}}}},"healthy":{"type":"boolean","description":"True when no gaps and no circuit breakers active"},"healInProgress":{"type":"boolean","description":"True when gap-fill was triggered recently"},"gapsFilled":{"type":"number","description":"Cumulative gap-fill count"},"totalAvailable":{"type":"number"},"totalReserved":{"type":"number"},"totalCapacity":{"type":"number"},"lastGapDetected":{"type":"string","nullable":true},"senderHands":{"type":"array","description":"Active sender hands — senders with held transactions waiting for nonce gap fill (capped at 50)","items":{"type":"object","properties":{"address":{"type":"string","description":"Sender Stacks address"},"nextExpected":{"type":"number","description":"Next sender nonce needed to unblock dispatch"},"handSize":{"type":"number","description":"Number of transactions held in the sender's hand"},"oldestEntryAge":{"type":"number","description":"Milliseconds since oldest entry was received"}}}},"recommendation":{"type":"string","nullable":true,"enum":["fallback_to_direct"],"description":"When non-null, clients should bypass sponsored submission"},"settlementTimes":{"type":"object","description":"Global broadcast-to-confirmation latency percentiles across all wallets (last 24h)","properties":{"p50":{"type":"number","description":"Median settlement time in milliseconds"},"p95":{"type":"number","description":"95th percentile settlement time in milliseconds"},"avg":{"type":"number","description":"Average settlement time in milliseconds"},"count":{"type":"number","description":"Number of confirmed transactions in the sample"}}},"timestamp":{"type":"string"}}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/nonce/reset":{"post":{"tags":["Nonce"],"summary":"Trigger on-demand nonce recovery","description":"Immediately trigger nonce gap recovery on the Nonce Durable Object without waiting for the 5-minute alarm cycle. Requires API key authentication.\n\n**resync** (default): Applies the same gap-aware logic as the alarm — GAP RECOVERY resets to lowest missing nonce, FORWARD BUMP advances to chain's possible_next_nonce, STALE DETECTION resets if idle and ahead of chain.\n\n**reset**: Hard resets the counter to `last_executed_tx_nonce + 1` — the safe floor that cannot conflict with any confirmed transaction.\n\n**clear-pools**: Wipes all per-wallet pool state and stored addresses. Pools reinitialize from Hiro on the next request. Use after wallet derivation changes.\n\n**clear-conflicts**: Zeroes out `conflictsDetected` and clears `lastGapDetected` without touching nonce pool state. Manual escape hatch when auto-clear hasn't fired yet and the health circuit breaker is blocking traffic.\n\n**flush-wallet**: Full wallet flush for a specific wallet index (requires `walletIndex` in body). Retracts all active dispatch_queue entries to the replay buffer, fills the entire nonce range with self-transfers (RBF for occupied slots, gap-fill for empty ones), and resets the wallet head to `last_executed+1`. Use when 18+ scattered gaps cause TooMuchChaining and surgical gap-filling is insufficient. Capped at 50 nonces per flush.","security":[{"bearerAuth":[]}],"operationId":"post_NonceReset","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["resync","reset","clear-pools","clear-conflicts","flush-wallet"],"default":"resync","description":"Recovery action to perform. 'resync' applies gap-aware reconciliation; 'reset' hard resets to last_executed_tx_nonce + 1; 'clear-pools' wipes all wallet pools for reinitialization; 'clear-conflicts' zeroes conflictsDetected and clears lastGapDetected without touching pool state; 'flush-wallet' performs a full wallet flush (requires walletIndex).","example":"resync"},"walletIndex":{"type":"number","minimum":0,"description":"Wallet index for the 'flush-wallet' action (0-based, required when action is 'flush-wallet'). Ignored for other actions.","example":0},"probeDepth":{"type":"number","minimum":1,"maximum":50,"description":"Backward probe depth for 'flush-wallet' when the forward nonce range is empty. Broadcasts self-transfers at nonces below last_executed to evict ghost mempool entries from the Stacks node. Only used with 'flush-wallet'.","example":25}},"description":"Optional action to perform (defaults to 'resync')"}}}},"responses":{"200":{"description":"Nonce recovery triggered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking"},"action":{"type":"string","enum":["resync","reset","clear-pools","clear-conflicts","flush-wallet"],"description":"Action that was performed"},"result":{"type":"object","description":"Result from the Nonce Durable Object (shape varies by action)","properties":{"success":{"type":"boolean"},"action":{"type":"string"},"previousNonce":{"type":"number","nullable":true,"description":"Nonce counter value before recovery (resync/reset)"},"newNonce":{"type":"number","nullable":true,"description":"Nonce counter value after recovery (resync/reset)"},"changed":{"type":"boolean","description":"Whether the nonce counter was modified (resync/reset)"},"reason":{"type":"string","description":"Human-readable reason for the change (resync only)"},"cleared":{"type":"boolean","description":"Whether conflict counters were cleared (clear-conflicts)"},"previousConflicts":{"type":"number","description":"Conflict count before clearing (clear-conflicts)"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"502":{"description":"Hiro API unavailable during nonce recovery","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}}}}},"/nonce/fill-gaps/{wallet}":{"post":{"tags":["Nonce"],"summary":"Fill nonce gaps for a specific wallet","description":"Immediately broadcast gap-fill transactions for all detected gaps in a specific wallet. Bypasses alarm rate limits (MAX_GAP_FILLS_PER_ALARM) and gap-fill throttle. Requires API key authentication.\n\nUse when a wallet is stuck due to nonce gaps blocking the chain head. Each gap-fill is a 1 uSTX transfer at 30k fee.","security":[{"bearerAuth":[]}],"operationId":"post_NonceFillGaps","responses":{"200":{"description":"Gap-fill results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"requestId":{"type":"string","format":"uuid"},"walletIndex":{"type":"number"},"address":{"type":"string"},"possible_next_nonce":{"type":"number"},"head":{"type":"number","nullable":true},"filled":{"type":"array","items":{"type":"object","properties":{"nonce":{"type":"number"},"txid":{"type":"string"}}}},"failed":{"type":"array","items":{"type":"object","properties":{"nonce":{"type":"number"},"reason":{"type":"string"}}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"502":{"description":"Hiro API unavailable during gap detection","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}}}}},"/nonce/history/{wallet}/{nonce}":{"get":{"tags":["Nonce"],"summary":"Get nonce event history","description":"Returns the nonce_intents row and full nonce_events audit trail for a specific (wallet_index, nonce) pair. Use this to diagnose broadcast failures, conflicts, and reconciliation outcomes for a single nonce.","operationId":"get_NonceHistory","responses":{"200":{"description":"Nonce history retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"intent":{"type":"object","nullable":true,"description":"Current nonce_intents row (null if not found)"},"events":{"type":"array","items":{"type":"object"},"description":"Ordered list of nonce_events for this (wallet, nonce) pair"},"timestamp":{"type":"string","description":"ISO timestamp of the response"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"503":{"description":"Service temporarily unavailable (e.g. nonce coordinator unreachable)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}}}}},"/nonce/surge-history":{"get":{"tags":["Nonce"],"summary":"Get surge event history","description":"Returns the last 20 pool-pressure surge events recorded by the nonce coordinator. A surge starts when overall pool pressure exceeds 80% and resolves when it drops below. Use this to identify recurring high-traffic windows and pre-provision sponsor wallets. Each resolved surge emits a surge_pattern log with time_of_day, day_of_week, peak_pressure_pct, and duration for capacity planning.","operationId":"get_NonceSurgeHistory","responses":{"200":{"description":"Surge history retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"surgeEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"started_at":{"type":"string","description":"ISO timestamp when surge started"},"peak_pressure_pct":{"type":"integer","description":"Peak pool pressure percentage (0-100)"},"peak_reserved":{"type":"integer","description":"Peak in-flight nonce count across all wallets"},"wallet_count_at_peak":{"type":"integer","description":"Number of sponsor wallets active at peak"},"duration_ms":{"type":"integer","nullable":true,"description":"Surge duration in milliseconds (null if still active)"},"resolved_at":{"type":"string","nullable":true,"description":"ISO timestamp when surge resolved (null if still active)"}}},"description":"List of surge events, most recent first (up to 20)"},"timestamp":{"type":"string","description":"ISO timestamp of the response"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"503":{"description":"Service temporarily unavailable (e.g. nonce coordinator unreachable)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"},"retryAfter":{"type":"number","description":"Seconds to wait before retrying"}}}}}}}}},"/settle":{"post":{"tags":["x402 V2"],"summary":"Settle an x402 V2 payment","description":"x402 V2 facilitator settle endpoint (spec section 7.2). Verifies payment parameters locally and broadcasts the transaction to the Stacks network. Auto-sponsors transactions with an empty sponsor slot (fee=0 / all-zeros signer) — standard x402 clients that build transactions with sponsored:true and fee:0 are handled transparently. Returns HTTP 200 for settlement results (success or failure); HTTP 400 for invalid request schema; HTTP 409 when a payment-identifier conflicts with a prior request.","operationId":"post_Settle","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["paymentPayload","paymentRequirements"],"properties":{"x402Version":{"type":"number","description":"x402 protocol version (optional at top level, library compat)","example":2},"paymentPayload":{"type":"object","description":"Client payment authorization","required":["payload"],"properties":{"x402Version":{"type":"number"},"payload":{"type":"object","required":["transaction"],"properties":{"transaction":{"type":"string","description":"Hex-encoded signed sponsored transaction","example":"0x00000001..."}}},"extensions":{"type":"object","description":"Optional protocol extensions","properties":{"payment-identifier":{"type":"object","description":"Client-controlled idempotency key (payment-identifier extension)","properties":{"info":{"type":"object","properties":{"id":{"type":"string","description":"16-128 char idempotency key (pattern: [a-zA-Z0-9_-]+, pay_ prefix recommended)","example":"pay_01JMVP9QE8XA3BDGM5RN7KWTZ4"}}}}}}}}},"paymentRequirements":{"type":"object","description":"Server payment requirements to validate against","required":["network","payTo","amount","asset"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","description":"CAIP-2 network identifier","example":"stacks:2147483648"},"amount":{"type":"string","description":"Required amount in smallest unit","example":"1000000"},"asset":{"type":"string","description":"Asset identifier (STX, sBTC, or CAIP-19 contract address)","example":"STX"},"payTo":{"type":"string","description":"Recipient Stacks address","example":"SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"},"maxTimeoutSeconds":{"type":"number","example":60}}}}}}}},"responses":{"200":{"description":"Settlement result (success or failure — check success field)","content":{"application/json":{"schema":{"type":"object","required":["success","transaction","network"],"properties":{"success":{"type":"boolean"},"errorReason":{"type":"string","description":"Error reason code if settlement failed","example":"recipient_mismatch"},"payer":{"type":"string","description":"Payer Stacks address (present on success or partial failure)","example":"SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7"},"transaction":{"type":"string","description":"Transaction ID on the network (empty string on pre-broadcast failure)","example":"0x1234..."},"network":{"type":"string","description":"CAIP-2 network identifier","example":"stacks:2147483648"},"extensions":{"type":"object","description":"Echoed protocol extensions (e.g. payment-identifier)"}}}}}},"400":{"description":"Invalid request — missing or malformed required fields","content":{"application/json":{"schema":{"type":"object","required":["success","errorReason","transaction","network"],"properties":{"success":{"type":"boolean","example":false},"errorReason":{"type":"string","example":"invalid_payload"},"transaction":{"type":"string","example":""},"network":{"type":"string","example":"stacks:2147483648"}}}}}},"409":{"description":"Payment-identifier conflict — same id used with a different payload","content":{"application/json":{"schema":{"type":"object","required":["success","errorReason","transaction","network"],"properties":{"success":{"type":"boolean","example":false},"errorReason":{"type":"string","example":"invalid_payload"},"transaction":{"type":"string","example":""},"network":{"type":"string","example":"stacks:2147483648"}}}}}},"500":{"description":"Unexpected internal error","content":{"application/json":{"schema":{"type":"object","required":["success","errorReason","transaction","network"],"properties":{"success":{"type":"boolean","example":false},"errorReason":{"type":"string","example":"unexpected_settle_error"},"transaction":{"type":"string","example":""},"network":{"type":"string","example":"stacks:2147483648"}}}}}}}}},"/settle/status/{txid}":{"get":{"tags":["x402 V2"],"summary":"Get transaction settlement status","description":"Returns the relay's internal view of a previously-settled transaction. Includes status (broadcast/pending/confirmed/failed), sponsor wallet info, and timestamps. Pass ?live=true to also fetch the current Hiro API status.","operationId":"get_SettleStatus","responses":{"200":{"description":"Transaction status found","content":{"application/json":{"schema":{"type":"object","required":["success","txid","status","network","broadcastAt"],"properties":{"success":{"type":"boolean"},"txid":{"type":"string"},"status":{"type":"string","enum":["broadcast","pending","confirmed","failed"]},"payer":{"type":"string"},"network":{"type":"string"},"walletIndex":{"type":"number"},"sponsorNonce":{"type":"number","nullable":true},"sponsorFee":{"type":"string"},"broadcastAt":{"type":"string"},"confirmedAt":{"type":"string"},"blockHeight":{"type":"number"},"errorReason":{"type":"string"},"hiroStatus":{"type":"object","nullable":true,"description":"Live Hiro API tx status (only when ?live=true)","properties":{"txStatus":{"type":"string"},"blockHeight":{"type":"number"}}}}}}}},"404":{"description":"Transaction not found in relay records","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/verify":{"post":{"tags":["x402 V2"],"summary":"Verify an x402 V2 payment (local validation only)","description":"x402 V2 facilitator verify endpoint (spec section 7.1). Validates payment parameters by deserializing the transaction locally — does NOT broadcast. Returns HTTP 200 for verification results; check isValid field. Returns HTTP 409 when a payment-identifier conflicts with a prior request.","operationId":"post_VerifyV2","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["paymentPayload","paymentRequirements"],"properties":{"x402Version":{"type":"number","description":"x402 protocol version (optional at top level, library compat)","example":2},"paymentPayload":{"type":"object","description":"Client payment authorization","required":["payload"],"properties":{"x402Version":{"type":"number"},"payload":{"type":"object","required":["transaction"],"properties":{"transaction":{"type":"string","description":"Hex-encoded signed sponsored transaction","example":"0x00000001..."}}},"extensions":{"type":"object","description":"Optional protocol extensions","properties":{"payment-identifier":{"type":"object","description":"Client-controlled idempotency key (payment-identifier extension)","properties":{"info":{"type":"object","properties":{"id":{"type":"string","description":"16-128 char idempotency key (pattern: [a-zA-Z0-9_-]+, pay_ prefix recommended)","example":"pay_01JMVP9QE8XA3BDGM5RN7KWTZ4"}}}}}}}}},"paymentRequirements":{"type":"object","description":"Server payment requirements to validate against","required":["network","payTo","amount","asset"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","description":"CAIP-2 network identifier","example":"stacks:2147483648"},"amount":{"type":"string","description":"Required amount in smallest unit","example":"1000000"},"asset":{"type":"string","description":"Asset identifier (STX, sBTC, or CAIP-19 contract address)","example":"STX"},"payTo":{"type":"string","description":"Recipient Stacks address","example":"SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"},"maxTimeoutSeconds":{"type":"number","example":60}}}}}}}},"responses":{"200":{"description":"Verification result (valid or invalid — check isValid field)","content":{"application/json":{"schema":{"type":"object","required":["isValid"],"properties":{"isValid":{"type":"boolean"},"invalidReason":{"type":"string","description":"Reason for invalidity if isValid is false","example":"recipient_mismatch"},"payer":{"type":"string","description":"Payer Stacks address (if determinable from transaction)","example":"SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7"},"extensions":{"type":"object","description":"Echoed protocol extensions (e.g. payment-identifier)"}}}}}},"409":{"description":"Payment-identifier conflict — same id used with a different payload","content":{"application/json":{"schema":{"type":"object","required":["isValid"],"properties":{"isValid":{"type":"boolean","example":false},"invalidReason":{"type":"string","example":"payment_identifier_conflict"}}}}}}}}},"/supported":{"get":{"tags":["x402 V2"],"summary":"Get supported x402 V2 payment kinds","description":"x402 V2 facilitator supported endpoint (spec section 7.3). Returns the static configuration of payment kinds supported by this relay: x402Version 2, scheme 'exact', on the configured Stacks network.","operationId":"get_Supported","responses":{"200":{"description":"Supported payment kinds configuration","content":{"application/json":{"schema":{"type":"object","required":["kinds","extensions","signers"],"properties":{"kinds":{"type":"array","items":{"type":"object","properties":{"x402Version":{"type":"number","example":2},"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"stacks:2147483648"}}}},"extensions":{"type":"array","items":{"type":"string"},"description":"Supported protocol extensions"},"signers":{"type":"object","description":"Map of network to supported signer addresses (empty = any signer accepted)","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}}},"/wallets":{"get":{"tags":["Wallets"],"summary":"Get per-wallet sponsor status","description":"Returns current STX balance, cumulative fees spent, transaction counts, live nonce pool state, and health status for each configured sponsor wallet. Balances are cached for 60 seconds. Use this endpoint to identify wallets that need funding. This is the detailed operator/debugging path; use GET /status/sponsor for the canonical cached sponsor readiness surface.","operationId":"get_Wallets","responses":{"200":{"description":"Wallet statuses retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"requestId":{"type":"string","format":"uuid","description":"Unique request identifier for tracking"},"wallets":{"type":"array","description":"Per-wallet status array ordered by wallet index","items":{"type":"object","properties":{"index":{"type":"number","description":"0-based BIP-44 account index"},"address":{"type":"string","description":"Stacks address for this wallet"},"balance":{"type":"string","description":"Current STX balance in microSTX"},"totalFeesSpent":{"type":"string","description":"Cumulative fees paid since tracking began (microSTX)"},"txCount":{"type":"number","description":"Total transactions sponsored by this wallet"},"txCountToday":{"type":"number","description":"Transactions sponsored today (UTC)"},"feesToday":{"type":"string","description":"Fees paid today in microSTX"},"gapFillFeesTotal":{"type":"string","description":"Cumulative fees paid for gap-fill txs in microSTX"},"gapFillCount":{"type":"number","description":"Number of gap-fill transactions broadcast for this wallet"},"pool":{"type":"object","description":"Live nonce pool state","properties":{"available":{"type":"number","description":"Nonces available for assignment"},"reserved":{"type":"number","description":"Nonces currently in-flight"},"maxNonce":{"type":"number","description":"Highest nonce in the pool"}}},"status":{"type":"string","enum":["healthy","low_balance","depleted"],"description":"healthy: balance >= 1 STX; low_balance: >= 0.1 STX; depleted: < 0.1 STX"}}}},"totals":{"type":"object","description":"Aggregate totals across all wallets","properties":{"totalBalance":{"type":"string","description":"Sum of all wallet balances in microSTX"},"totalFeesSpent":{"type":"string","description":"Sum of all fees ever paid in microSTX"},"totalTxCount":{"type":"number","description":"Total transactions across all wallets"},"walletCount":{"type":"number","description":"Number of configured sponsor wallets"}}},"thresholds":{"type":"object","description":"Balance thresholds used to classify wallet health (microSTX)","properties":{"lowBalanceWarning":{"type":"string","example":"1000000"},"depletedThreshold":{"type":"string","example":"100000"}}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/payment/{id}":{"get":{"tags":["Payment"],"summary":"Check payment status","description":"Returns the current status of a payment submitted via RPC queue. No authentication required. The payment ID is passed as a URL path parameter.","operationId":"get_PaymentStatus","responses":{"200":{"description":"Payment status found","content":{"application/json":{"schema":{"type":"object","required":["success","requestId","paymentId","status","submittedAt"],"properties":{"success":{"type":"boolean"},"requestId":{"type":"string"},"paymentId":{"type":"string"},"status":{"type":"string","enum":["queued","broadcasting","mempool","confirmed","failed","replaced"]},"terminalReason":{"type":"string"},"txid":{"type":"string"},"blockHeight":{"type":"number"},"explorerUrl":{"type":"string"},"checkStatusUrl":{"type":"string"},"senderAddress":{"type":"string"},"senderNonce":{"type":"number"},"sponsorFee":{"type":"string"},"error":{"type":"string"},"errorCode":{"type":"string"},"retryable":{"type":"boolean"},"submittedAt":{"type":"string"},"queuedAt":{"type":"string"},"mempoolAt":{"type":"string"},"confirmedAt":{"type":"string"},"failedAt":{"type":"string"},"replacedAt":{"type":"string"},"replacedReason":{"type":"string"},"replacementTxid":{"type":"string"},"resubmittable":{"type":"boolean"},"senderNonceInfo":{"type":"object"},"relayState":{"type":"string"},"holdReason":{"type":"string"},"nextExpectedNonce":{"type":"number"},"missingNonces":{"type":"array","items":{"type":"number"}},"holdExpiresAt":{"type":"string"},"senderWedge":{"type":"object"}}}}}},"404":{"description":"Payment not found or expired","content":{"application/json":{"schema":{"type":"object","required":["success","requestId","paymentId","status","terminalReason","error","retryable"],"properties":{"success":{"type":"boolean"},"requestId":{"type":"string"},"paymentId":{"type":"string"},"status":{"type":"string","enum":["not_found"]},"terminalReason":{"type":"string","enum":["expired","unknown_payment_identity"]},"error":{"type":"string"},"retryable":{"type":"boolean"},"checkStatusUrl":{"type":"string"}}}}}}}}},"/webhook/chainhook":{"post":{"tags":["Webhook"],"summary":"Chainhook transaction webhook","description":"Receives Hiro chainhook events for sponsor wallet transactions. Updates payment status and sender nonce cache on confirmation or abort.","operationId":"post_Chainhook","requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Hiro chainhook payload"}}}},"responses":{"200":{"description":"Webhook processed"},"401":{"description":"Invalid or missing auth token"}}}},"/queue/{senderAddress}":{"get":{"tags":["Nonce"],"summary":"Agent queue state","description":"Returns the agent's pending transaction queue state across all sponsor wallets. Requires a SIP-018 signature with action \"queue-read\" from the sender's Stacks key. Auth is passed via X-SIP018-Auth header (JSON-encoded {signature, message}). Returns queued, dispatched, replaying, and replay_buffer entries.","operationId":"get_QueueRead","responses":{"200":{"description":"Queue state retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"requestId":{"type":"string","format":"uuid"},"queue":{"type":"object","properties":{"queued":{"type":"array","items":{"type":"object","properties":{"walletIndex":{"type":"number"},"sponsorNonce":{"type":"number"},"senderNonce":{"type":"number"},"queuedAt":{"type":"string"}}}},"dispatched":{"type":"array","items":{"type":"object","properties":{"walletIndex":{"type":"number"},"sponsorNonce":{"type":"number"},"senderNonce":{"type":"number"},"queuedAt":{"type":"string"},"dispatchedAt":{"type":"string","nullable":true}}}},"replaying":{"type":"array","items":{"type":"object","properties":{"walletIndex":{"type":"number"},"sponsorNonce":{"type":"number"},"senderNonce":{"type":"number"},"queuedAt":{"type":"string"}}}},"held":{"type":"array","items":{"type":"object","properties":{"paymentId":{"type":"string"},"senderNonce":{"type":"number"},"source":{"type":"string"},"receivedAt":{"type":"string"},"expiresAt":{"type":"string"}}}},"replayBuffer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"walletIndex":{"type":"number"},"paymentId":{"type":"string"},"originalSponsorNonce":{"type":"number"},"senderNonce":{"type":"number"},"queuedAt":{"type":"string"}}}},"senderWedge":{"type":"object","properties":{"senderAddress":{"type":"string"},"blocked":{"type":"boolean"},"blockedOnFrontierMismatch":{"type":"boolean"},"adminRecoveryLikely":{"type":"boolean"},"nextExpectedNonce":{"type":"number","nullable":true},"lowestHeldNonce":{"type":"number","nullable":true},"missingNonces":{"type":"array","items":{"type":"number"}},"heldCount":{"type":"number"},"oldestHeldAgeMs":{"type":"number","nullable":true},"lastRepairAttemptAt":{"type":"string","nullable":true},"lastRepairFailureAt":{"type":"string","nullable":true},"repairEligible":{"type":"boolean"},"repairTriggered":{"type":"boolean"},"repairAdvanced":{"type":"boolean"},"activePaymentIds":{"type":"array","items":{"type":"string"}}}},"total":{"type":"number"}}}}}}}},"401":{"description":"Invalid or expired SIP-018 signature","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"403":{"description":"Address mismatch — signature does not prove ownership of senderAddress","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string","example":"QUEUE_ACCESS_DENIED"},"retryable":{"type":"boolean","example":false}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}},"/queue/{senderAddress}/{walletIndex}/{sponsorNonce}":{"delete":{"tags":["Nonce"],"summary":"Cancel a queued transaction","description":"Cancels a queued, dispatched, or replaying sponsored transaction. Requires a SIP-018 signature with action \"queue-cancel\" from the sender's Stacks key. The recovered signer address must match the :senderAddress URL parameter.\n\nState transitions:\n- queued → deleted immediately\n- dispatched → sponsor nonce flushed immediately (best-effort via RBF), then deleted\n- replaying → deleted immediately\n- replay_buffer entry (matched by original_sponsor_nonce) → deleted","operationId":"delete_QueueCancel","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["auth"],"properties":{"auth":{"type":"object","required":["signature","message"],"description":"SIP-018 structured data signature proving ownership of senderAddress","properties":{"signature":{"type":"string","description":"RSV hex signature"},"message":{"type":"object","required":["action","nonce","expiry"],"properties":{"action":{"type":"string","enum":["queue-cancel"]},"nonce":{"type":"string","description":"Unix timestamp ms"},"expiry":{"type":"string","description":"Expiry unix timestamp ms"}}}}}}}}}},"responses":{"200":{"description":"Transaction cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"requestId":{"type":"string","format":"uuid"},"cancelled":{"type":"object","properties":{"cancelled":{"type":"boolean"},"previousState":{"type":"string","enum":["queued","dispatched","replaying","replay_buffer"]},"walletIndex":{"type":"number"},"sponsorNonce":{"type":"number"}}}}}}}},"401":{"description":"Invalid or expired SIP-018 signature","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"403":{"description":"Address mismatch — signature does not prove ownership of senderAddress","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string","example":"QUEUE_ACCESS_DENIED"},"retryable":{"type":"boolean","example":false}}}}}},"404":{"description":"Queue entry not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"requestId":{"type":"string","format":"uuid"},"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}}},"webhooks":{}}