{"openapi":"3.1.0","info":{"title":"Gateway service agent API","version":"1.0.0","description":"Release candidate. Wallet payments disabled by default; Base Sepolia testnet and separately activated Base mainnet USDC. x402 payment settles an asynchronous job receipt. Existing PayPal checkout remains on human service pages. No production payment readiness claim."},"servers":[{"url":"https://gateway-wallet-payments.jerryrnapier.workers.dev","description":"Dedicated wallet API"}],"paths":{"/tip.json":{"get":{"operationId":"getTipDescriptor","security":[],"responses":{"200":{"description":"Free voluntary contribution discovery; never a payment challenge."}}}},"/tip.md":{"get":{"operationId":"getTipInstructions","security":[],"responses":{"200":{"description":"Free human and agent contribution instructions."}}}},"/api/agent/v1/tips":{"post":{"operationId":"createVoluntaryTipQuote","security":[{"capability":[]}],"description":"Explicit optional contribution only. No service, report, ranking or priority is purchased. Reserve a durable quote; payment uses its paymentUrl and the standard x402 flow. Confirmation requires finalized-chain evidence; never resubmit an uncertain payment.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["amount"],"properties":{"amount":{"type":"string","maxLength":79,"pattern":"^(?:0|[1-9][0-9]{0,71})(?:\\.[0-9]{1,6})?$","description":"USDC decimal string, minimum 0.01, no Gateway amount cap, at most 6 decimal places. Atomic amount must fit uint256; token balance and provider acceptance apply.","examples":["1.00","0.010001"]}}}}}},"responses":{"200":{"description":"Durable quote/job receipt; not proof that a report has completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"201":{"description":"Durable quote/job receipt; not proof that a report has completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"400":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/catalog":{"get":{"operationId":"getServiceCatalog","security":[],"responses":{"200":{"description":"Service catalog; no generation or payment.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/agent/v1/openapi":{"get":{"operationId":"getOpenApi","security":[],"responses":{"200":{"description":"This OpenAPI document."}}}},"/api/agent/v1/quotes":{"post":{"operationId":"createQuote","security":[{"capability":[]}],"description":"Validate bounded input and reserve an immutable quote. Does not scan, analyze, charge or require email. Same key and body returns the same receipt; changed payload is a conflict.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"https://gateway-wallet-payments.jerryrnapier.workers.dev/agent/quote-request.schema.json"}}}},"responses":{"200":{"description":"Durable quote/job receipt; not proof that a report has completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"201":{"description":"Durable quote/job receipt; not proof that a report has completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"400":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/quotes/{id}/pay":{"post":{"operationId":"payQuote","security":[{"capability":[]}],"description":"First request without PAYMENT-SIGNATURE obtains the x402 v2 PAYMENT-REQUIRED challenge if enabled. A compatible wallet signs the exact challenge. Repeat with PAYMENT-SIGNATURE (base64 JSON). Only confirmed settlement permits fulfillment. Payment verification alone does not. Keep the same receipt across uncertain responses.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Durable quote/job receipt; not proof that a report has completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"202":{"description":"Durable receipt or payment-in-progress notice; poll existing status. Do not resubmit a new payment.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Receipt"},{"$ref":"#/components/schemas/Error"}]}}}},"400":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required; base64 x402 v2 requirements are in PAYMENT-REQUIRED.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"404":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/jobs/{id}":{"get":{"operationId":"getJob","security":[{"capability":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Durable quote/job receipt; not proof that a report has completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"401":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/jobs/{id}/result":{"get":{"operationId":"getResult","security":[{"capability":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Private structured fulfillment. Preserve limitations and unknown/inconclusive states.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"https://gateway-wallet-payments.jerryrnapier.workers.dev/agent/website-scanner-result.schema.json"},{"$ref":"https://gateway-wallet-payments.jerryrnapier.workers.dev/agent/gti-preflight-result.schema.json"},{"$ref":"#/components/schemas/ContributionReceipt"}]}}}},"202":{"description":"Not ready; inspect status and respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"401":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable failure. Follow code and Retry-After; do not blindly retry payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"capability":{"type":"http","scheme":"bearer","bearerFormat":"64 lowercase hexadecimal characters","description":"Generate a random 32-byte secret locally. It owns access independently of wallet/payment identity. Header only; retain securely, redact from logs."}},"schemas":{"ContributionReceipt":{"type":"object","required":["service","kind","confirmation","amount","currency"],"properties":{"service":{"const":"voluntary-tip"},"kind":{"const":"contribution-receipt"},"confirmation":{"const":"finalized-chain"},"amount":{"type":"string"},"currency":{"const":"USDC"},"voluntary":{"const":true},"evidence":{"type":"object"}}},"Error":{"type":"object","required":["ok","code"],"properties":{"ok":{"const":false},"code":{"type":"string"},"message":{"type":"string"},"retryAfterSeconds":{"type":"integer"}}},"Receipt":{"type":"object","required":["ok","quoteId","jobId","status","paymentState","quoteExpiresAt","statusUrl","resultUrl","paymentUrl","price"],"properties":{"ok":{"const":true},"quoteId":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string"},"paymentState":{"type":"string"},"quoteExpiresAt":{"type":"string"},"expiresAt":{"type":"string"},"failureCode":{"type":["string","null"]},"statusUrl":{"type":"string"},"resultUrl":{"type":"string"},"paymentUrl":{"type":"string"},"price":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string","description":"Fixed service price or immutable voluntary contribution amount."},"currency":{"const":"USD"}}}}}}},"x-mcp":{"url":"https://gateway-wallet-payments.jerryrnapier.workers.dev/mcp","transport":"streamable-http","guide":"https://gateway-wallet-payments.jerryrnapier.workers.dev/agent/mcp-guide.md","paymentSubmission":false}}