{"openapi":"3.1.0","info":{"title":"StorkHost x402 API","version":"1.0.0","description":"Agent-first hosting. This document lists the key-less x402 resource only: a top-up of hosting credit paid in USDC on Base (x402 versions 1 and 2, scheme exact; StorkHost settles on-chain itself and pays gas). The full API, which uses an API key, is at https://api.storkhost.cloud/v3/api-docs.","contact":{"name":"StorkHost","url":"https://storkhost.cloud","email":"support@storkhost.cloud"},"x-guidance":"The payer must be the wallet a StorkHost account was signed up with (GET /v1/accounts/nonce, then POST /v1/accounts); that account is credited. A wallet without an account is refused with 402 before anything is charged. HTTP 202 means pending: poll the Location URL without a key, and do not sign a second payment meanwhile. Read the balance with the account's API key at GET /v1/account."},"servers":[{"url":"https://api.storkhost.cloud"}],"externalDocs":{"description":"Full StorkHost API (API key)","url":"https://api.storkhost.cloud/v3/api-docs"},"x-agentcash-guidance":{"llmsTxtUrl":"https://api.storkhost.cloud/llms.txt"},"paths":{"/v1/x402/topup":{"get":{"operationId":"x402Topup","summary":"Top up StorkHost hosting credit with x402 (USDC on Base, no API key)","description":"Without a payment header: HTTP 402 with the x402 version 2 PaymentRequired object in the PAYMENT-REQUIRED header (scheme exact, network eip155:8453, bazaar metadata) and the version 1 requirements in the JSON body. Sign an EIP-3009 TransferWithAuthorization with your signup wallet and retry with PAYMENT-SIGNATURE (version 2) or X-PAYMENT (version 1). The account bound to the paying wallet is credited. Accepted validity window (server clock): validAfter at most 5 s ahead; validBefore more than 10 s and at most 360 s ahead (maxTimeoutSeconds + 60). A malformed or refused payment header gets 402, not 400. Browser clients may call it from any origin (CORS, no credentials).","tags":["x402"],"security":[],"parameters":[{"name":"amountUsd","in":"query","required":false,"description":"Top-up in USD, cents only, from 1.00 to 1000.00; default 5.00. The 402 names the exact USDC amount to sign.","schema":{"type":"string","pattern":"^[0-9]{1,4}(\\.[0-9]{1,2})?$","default":"5.00","examples":["5.00"]}}],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"1.00","max":"1000.00"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Credited. Receipt in PAYMENT-RESPONSE (version 2) or X-PAYMENT-RESPONSE (version 1).","content":{"application/json":{"schema":{"type":"object","description":"Status only: never the account, balance or ledger.","properties":{"id":{"type":"string","description":"Settlement id (xau_...)"},"status":{"type":"string","enum":["PENDING","CONFIRMED","FAILED","REVIEW"]},"transaction":{"type":"string","description":"Settlement transaction hash on Base"},"payer":{"type":"string"},"network":{"type":"string","description":"CAIP-2, whatever x402 version paid (the version 1 receipt header says base)","examples":["eip155:8453"]},"amountAtomic":{"type":"string","description":"USDC, 6 decimals"},"amountUsd":{"type":"string"},"pollUrl":{"type":"string","description":"Status URL, no key needed"},"error":{"type":"string"}},"required":["id","status","network","amountAtomic","amountUsd","pollUrl"]}}}},"202":{"description":"Settlement pending: poll the absolute Location URL (GET /v1/x402/topup/exact/{id}, no key) no faster than Retry-After.","content":{"application/json":{"schema":{"type":"object","description":"Status only: never the account, balance or ledger.","properties":{"id":{"type":"string","description":"Settlement id (xau_...)"},"status":{"type":"string","enum":["PENDING","CONFIRMED","FAILED","REVIEW"]},"transaction":{"type":"string","description":"Settlement transaction hash on Base"},"payer":{"type":"string"},"network":{"type":"string","description":"CAIP-2, whatever x402 version paid (the version 1 receipt header says base)","examples":["eip155:8453"]},"amountAtomic":{"type":"string","description":"USDC, 6 decimals"},"amountUsd":{"type":"string"},"pollUrl":{"type":"string","description":"Status URL, no key needed"},"error":{"type":"string"}},"required":["id","status","network","amountAtomic","amountUsd","pollUrl"]}}}},"400":{"description":"amountUsd is malformed or outside 1.00 to 1000.00; the message states both limits."},"402":{"description":"Payment Required: requirements in PAYMENT-REQUIRED (version 2) and the body (version 1); after a refused payment, error says why and that nothing was charged."},"429":{"description":"Too many requests; see Retry-After."},"503":{"description":"Settlement delayed; retry the same authorization after Retry-After, do not sign a new one."}}}}}}