{"openapi":"3.1.0","info":{"title":"KotyTech USDC Payment Intelligence","version":"0.3.0","description":"Base and Base Sepolia USDC verification contract with billing on Base Mainnet.","x-guidance":"Match one native USDC Transfer with two RPC sources and report chain-aware finality."},"servers":[{"url":"https://api.kotytech.co"}],"paths":{"/v1/payments/verify":{"post":{"operationId":"verifyUsdcPayment","summary":"Match one USDC payment and observe Base finality","description":"USDC payment intent and Base finality verification using two RPC sources","security":[],"x-x402":{"version":2,"scheme":"exact","network":"eip155:8453","amount":"5000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0xBeb25e74d68104CE91BF269842c97507275aDBb1","currency":"USDC","discoveryEnabled":false,"discoveryMetadataAvailable":true,"publicationEnabled":false,"admission":"active"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationInput"},"example":{"network":"eip155:8453","transactionHash":"0xba1d0239f3e8bb67c26ed25f05feb1bacdf4ec3054a56c397a13c18e30bbec61","expectedRecipient":"0x2000000000000000000000000000000000000002","expectedTokenContract":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","expectedAmountAtomic":"10000","expectedSender":"0x1000000000000000000000000000000000000001"}}}},"responses":{"200":{"description":"Completed observation, including negative, pending or unknown outcomes. These 200 decisions are billed. verified=true requires finalized matching payment.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}},"PAYMENT-RESPONSE":{"description":"Base64 x402 v2 API-payment settlement receipt.","schema":{"type":"string"}},"X-Idempotent-Replay":{"description":"true only when returning a saved settled response; checkedAt and original requestId remain unchanged.","schema":{"type":"boolean"}},"X-Retry-Request-ID":{"description":"Current HTTP attempt ID for a cached response; X-Request-ID remains the original operation ID.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResult"}}}},"400":{"description":"Invalid JSON/input/payment authorization.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API payment required or rejected.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}},"PAYMENT-REQUIRED":{"description":"Base64 x402 v2 payment requirements. Present on a payment challenge; inspect exact network, asset, amount and recipient before authorizing.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"PROVIDER_CONFLICT (no settlement) or PAYMENT_ALREADY_USED (existing operation, changed body/route/proof, concurrent execution or uncertain settlement). Reconcile before creating a replacement payment.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"JSON body exceeds 2048 bytes.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required; compression is unsupported.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unsupported token contract for this network.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached before business work.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds before a capacity/rate retry, when applicable.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected application or payment-gateway error. Do not credit an invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"API-payment facilitator failure; settlement outcome may be indeterminate.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"RPC_UNAVAILABLE, RPC_INVALID_RESPONSE, RPC_RATE_LIMITED, RPC_BUSY, VERIFICATION_BUSY, PAYMENT_BUSY or PAYMENT_STORAGE_UNAVAILABLE. No new settlement is requested when computation/storage fails before settlement; a transport/storage failure after broadcast may already be charged.","headers":{"X-Request-ID":{"description":"Opaque request identifier; no wallet or transaction data.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds before a capacity/rate retry, when applicable.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"parameters":[{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"description":"Optional x402 v2 payment proof, not a separately provisioned API key. Absence negotiates HTTP 402. Execution requires both a valid proof and a valid JSON body.","schema":{"type":"string","maxLength":8192}}]}},"/health":{"get":{"summary":"Application liveness","description":"Public liveness only; does not promise provider availability.","security":[],"responses":{"200":{"description":"Application is running."}}}},"/ready":{"get":{"summary":"Dependency readiness","description":"Public bounded/cached chain-ID probes of both providers on both analysis networks, facilitator capabilities and a durable-storage write check. This does not prove receipt or finality completeness for any particular transaction.","security":[],"responses":{"200":{"description":"Dependencies reachable at last bounded probe."},"503":{"description":"A required dependency is unavailable or not yet checked."}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"Free canonical OpenAPI contract","security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON. Server origin is operator-configured or the bound loopback listener; no caller Host inference.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/x402":{"get":{"operationId":"getX402Discovery","summary":"Free x402scan-compatible resource fan-out","security":[],"responses":{"200":{"description":"Discovery metadata only; not a marketplace registration.","content":{"application/json":{"schema":{"type":"object","required":["version","resources"],"properties":{"version":{"const":1},"resources":{"type":"array","items":{"type":"string","format":"uri"}}}}}}}}}}},"components":{"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 base64 payload. A normal unpaid POST returns 402 payment requirements. The verification server never signs transactions."}},"schemas":{"Address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Nonzero EVM address. Mixed-case addresses must pass EIP-55."},"Hash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"IntegerText":{"type":"string","pattern":"^(0|[1-9][0-9]*)$"},"VerificationInput":{"type":"object","additionalProperties":false,"properties":{"network":{"type":"string","enum":["eip155:84532","eip155:8453"],"description":"Network of the transaction under analysis. The payment challenge specifies the billing network."},"transactionHash":{"$ref":"#/components/schemas/Hash"},"expectedRecipient":{"$ref":"#/components/schemas/Address"},"expectedTokenContract":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Issuer-listed USDC only: Base 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913; Base Sepolia 0x036CbD53842c5426634e7929541eC2318f3dCF7e."},"expectedAmountAtomic":{"type":"string","pattern":"^[1-9][0-9]{0,77}$","description":"Positive uint256 as canonical decimal text, never a JSON number. USDC has six decimals; 10000 is 0.01 USDC. Maximum 2^256-1."},"expectedSender":{"$ref":"#/components/schemas/Address"}},"required":["network","transactionHash","expectedRecipient","expectedTokenContract","expectedAmountAtomic"]},"Head":{"type":"object","additionalProperties":false,"properties":{"number":{"$ref":"#/components/schemas/IntegerText"},"hash":{"$ref":"#/components/schemas/Hash"}},"required":["number","hash"]},"Transfer":{"type":"object","additionalProperties":false,"properties":{"from":{"$ref":"#/components/schemas/Address"},"to":{"$ref":"#/components/schemas/Address"},"amountAtomic":{"$ref":"#/components/schemas/IntegerText"},"logIndex":{"$ref":"#/components/schemas/IntegerText"},"eventId":{"type":"string","description":"network:transactionHash:decimalLogIndex. Enforce unique consumption in the merchant ledger."}},"required":["from","to","amountAtomic","logIndex","eventId"]},"VerificationResult":{"type":"object","additionalProperties":false,"properties":{"requestId":{"type":"string","format":"uuid"},"network":{"type":"string","enum":["eip155:84532","eip155:8453"],"description":"Network of the transaction under analysis. The payment challenge specifies the billing network."},"transactionHash":{"$ref":"#/components/schemas/Hash"},"checkedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","included","safe","finalized","failed","unknown"]},"verified":{"type":"boolean","description":"True only for exactly one matching, successfully executed USDC Transfer and finalized status. Never credit on inclusion alone."},"verificationPolicy":{"const":"one_exact_usdc_transfer_and_finalized"},"transaction":{"type":"object","additionalProperties":false,"properties":{"exists":{"type":"boolean"},"execution":{"enum":["success","failed","pending","unknown"]},"blockNumber":{"anyOf":[{"$ref":"#/components/schemas/IntegerText"},{"type":"null"}]},"blockHash":{"anyOf":[{"$ref":"#/components/schemas/Hash"},{"type":"null"}]}},"required":["exists","execution","blockNumber","blockHash"]},"payment":{"type":"object","additionalProperties":false,"properties":{"matched":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}},"matchingTransferCount":{"type":"integer","minimum":0},"transfer":{"anyOf":[{"$ref":"#/components/schemas/Transfer"},{"type":"null"}]}},"required":["matched","reasons","matchingTransferCount","transfer"]},"finality":{"type":"object","additionalProperties":false,"properties":{"status":{"enum":["included","safe","finalized","unknown"]},"source":{"const":"rpc_block_tags"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"safeHead":{"anyOf":[{"$ref":"#/components/schemas/Head"},{"type":"null"}]},"finalizedHead":{"anyOf":[{"$ref":"#/components/schemas/Head"},{"type":"null"}]}},"required":["status","source","reason","safeHead","finalizedHead"]},"evidence":{"type":"object","additionalProperties":false,"properties":{"providers":{"type":"array","prefixItems":[{"const":"primary"},{"const":"secondary"}],"minItems":2,"maxItems":2},"agreement":{"const":"agreed"},"rpcCalls":{"type":"integer","minimum":0,"maximum":54},"receiptBlockCanonical":{"type":"boolean"}},"required":["providers","agreement","rpcCalls","receiptBlockCanonical"]}},"required":["requestId","network","transactionHash","checkedAt","status","verified","verificationPolicy","transaction","payment","finality","evidence"]},"Error":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","pattern":"^[A-Z_]+$"},"message":{"type":"string"}},"required":["code","message"]},"status":{"const":"unknown"},"verified":{"const":false},"requestId":{"type":"string","format":"uuid"}},"required":["error"]}}}}