{"openapi":"3.1.0","info":{"title":"tx402 API","version":"0.2.0","description":"Deterministic explanations of Algorand transactions, atomic groups, batches, and account activity, sold as pay-per-call APIs with x402."},"servers":[{"url":"https://tx402-production.up.railway.app","description":"Production"},{"url":"http://localhost:4021","description":"Local development"}],"paths":{"/health":{"get":{"summary":"Health check","description":"Plain liveness check by default. Add deep=1 for readiness checks against upstream services.","parameters":[{"name":"deep","in":"query","required":false,"schema":{"type":"string","enum":["1"]}},{"name":"network","in":"query","required":false,"schema":{"type":"string","enum":["mainnet","testnet"],"default":"mainnet"}}],"responses":{"200":{"description":"Service is live or ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"400":{"description":"Invalid deep-health network parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Deep health rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Deep readiness check failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/discovery":{"get":{"summary":"Discovery metadata","description":"Machine-readable description of what tx402 sells and whether /explain is priced.","responses":{"200":{"description":"Discovery metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoveryResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/openapi.json":{"get":{"summary":"OpenAPI specification","responses":{"200":{"description":"OpenAPI 3.1 document for this API.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent.json":{"get":{"summary":"Agent manifest","description":"Machine-readable metadata for agent marketplaces and x402 crawlers.","responses":{"200":{"description":"Agent manifest.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/x402":{"get":{"summary":"x402 resource manifest","description":"Machine-readable list of paid x402 resources exposed by tx402.","responses":{"200":{"description":"x402 manifest.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/llms.txt":{"get":{"summary":"LLM-readable service documentation","responses":{"200":{"description":"Plain-text documentation for agents and crawlers.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/demo":{"get":{"summary":"Try a free transaction explanation","description":"Returns a complete explanation for one of two fixed Algorand Mainnet examples. No wallet or payment is required, and arbitrary transaction IDs are not accepted.","parameters":[{"name":"example","in":"query","required":false,"schema":{"type":"string","enum":["algo","usdc"],"default":"algo"}}],"responses":{"200":{"description":"Free example transaction explanation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoResponse"}}}},"400":{"description":"Unknown demo example.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Demo rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/analytics":{"get":{"summary":"Aggregate adoption analytics","description":"Process-local counters with no cookies, IP history, query strings, or wallet addresses retained.","responses":{"200":{"description":"Privacy-conscious aggregate adoption counters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/group":{"get":{"summary":"Explain an Algorand atomic transaction group","description":"Resolves the complete group containing txid, including nested inner transactions, transfers, fees, and verified protocol calls. Production requires x402 payment.","parameters":[{"name":"txid","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Z2-7]{52}$"}},{"name":"network","in":"query","required":false,"schema":{"type":"string","enum":["mainnet","testnet"],"default":"mainnet"}}],"responses":{"200":{"description":"Complete group explanation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupResponse"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"x402 payment required.","headers":{"payment-required":{"schema":{"type":"string"}}}},"404":{"description":"Transaction or group not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/batch":{"post":{"summary":"Explain a batch of Algorand transactions","description":"Explains 1 to 10 unique transaction IDs with per-item success or error results. Production requires x402 payment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["txids"],"properties":{"txids":{"type":"array","minItems":1,"maxItems":10,"uniqueItems":true,"items":{"type":"string","pattern":"^[A-Z2-7]{52}$"}},"network":{"type":"string","enum":["mainnet","testnet"],"default":"mainnet"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Batch explanation with per-item results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"x402 payment required.","headers":{"payment-required":{"schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/account/activity":{"get":{"summary":"Summarize recent Algorand account activity","description":"Aggregates asset flows, fees, counterparties, transaction types, and verified protocol interactions for portfolio and compliance agents. Production requires x402 payment.","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","minLength":58,"maxLength":58}},{"name":"network","in":"query","required":false,"schema":{"type":"string","enum":["mainnet","testnet"],"default":"mainnet"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":25}}],"responses":{"200":{"description":"Account activity summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountActivityResponse"}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"x402 payment required.","headers":{"payment-required":{"schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/explain":{"get":{"summary":"Explain an Algorand transaction","description":"Returns a plain-English explanation and normalized details for one Algorand transaction. Production requires x402 payment.","parameters":[{"name":"txid","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Z2-7]{52}$","minLength":52,"maxLength":52}},{"name":"network","in":"query","required":false,"schema":{"type":"string","enum":["mainnet","testnet"],"default":"mainnet"}}],"responses":{"200":{"description":"Transaction explanation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainResponse"}}}},"400":{"description":"Missing or invalid txid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The x402 payment challenge is returned in the payment-required response header.","headers":{"payment-required":{"description":"Base64-encoded x402 payment challenge.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Transaction not found on the selected network.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Indexer or upstream dependency returned an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Indexer request timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"HealthResponse":{"type":"object","required":["ok","service","version"],"properties":{"ok":{"type":"boolean"},"service":{"type":"string","const":"tx402"},"version":{"type":"string"},"checks":{"type":"object","properties":{"indexer":{"type":"boolean"},"facilitator":{"oneOf":[{"type":"boolean"},{"type":"string","const":"not configured"}]}}}}},"DiscoveryResponse":{"type":"object","required":["service","summary","routes","deterministic","llmInServingPath"],"properties":{"service":{"type":"string","const":"tx402"},"summary":{"type":"string"},"routes":{"type":"array","items":{"type":"object","required":["path","method","params","priced","price","paymentProtocol"],"properties":{"path":{"type":"string"},"method":{"type":"string"},"params":{"type":"object"},"priced":{"type":"boolean"},"price":{"type":["string","null"]},"paymentProtocol":{"type":["string","null"]}}}},"deterministic":{"type":"boolean"},"llmInServingPath":{"type":"boolean"}}},"ExplainResponse":{"type":"object","required":["txid","network","summary","details"],"properties":{"txid":{"type":"string"},"network":{"type":"string","enum":["mainnet","testnet"]},"summary":{"type":"string"},"details":{"$ref":"#/components/schemas/DecodedTransaction"}}},"DemoResponse":{"allOf":[{"$ref":"#/components/schemas/ExplainResponse"},{"type":"object","required":["demo","example","label"],"properties":{"demo":{"type":"boolean","const":true},"example":{"type":"string","enum":["algo","usdc"]},"label":{"type":"string"}}}]},"GroupResponse":{"type":"object","required":["anchorTxid","network","atomic","summary","transactionCount","transactions"],"properties":{"anchorTxid":{"type":"string"},"network":{"type":"string","enum":["mainnet","testnet"]},"groupId":{"type":["string","null"]},"atomic":{"type":"boolean"},"summary":{"type":"string"},"transactionCount":{"type":"integer"},"innerTransactionCount":{"type":"integer"},"protocols":{"type":"array","items":{"$ref":"#/components/schemas/VerifiedProtocol"}},"transfers":{"type":"array","items":{"type":"object","additionalProperties":true}},"transactions":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"BatchResponse":{"type":"object","required":["network","requested","succeeded","failed","results"],"properties":{"network":{"type":"string","enum":["mainnet","testnet"]},"requested":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"AccountActivityResponse":{"type":"object","required":["address","network","summary","transactionCount","totals","recentTransactions"],"properties":{"address":{"type":"string"},"network":{"type":"string","enum":["mainnet","testnet"]},"summary":{"type":"string"},"transactionCount":{"type":"integer"},"uniqueCounterparties":{"type":"integer"},"totals":{"type":"object","additionalProperties":true},"protocols":{"type":"array","items":{"$ref":"#/components/schemas/VerifiedProtocol"}},"recentTransactions":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"VerifiedProtocol":{"type":"object","required":["protocol","application","appId","source"],"properties":{"protocol":{"type":"string"},"application":{"type":"string"},"component":{"type":"string"},"category":{"type":"string"},"appId":{"type":"integer"},"source":{"type":"string","format":"uri"}}},"AnalyticsResponse":{"type":"object","required":["service","since","privacy","funnel","routes"],"properties":{"service":{"type":"string","const":"tx402"},"since":{"type":"string","format":"date-time"},"privacy":{"type":"object","additionalProperties":{"type":"boolean"}},"funnel":{"type":"object","additionalProperties":true},"routes":{"type":"object","additionalProperties":true}}},"DecodedTransaction":{"type":"object","required":["txid","type","typeLabel","sender","senderShort","fee","confirmedRound","timestamp","note","groupId","isGrouped","application"],"properties":{"txid":{"type":"string"},"type":{"type":"string"},"typeLabel":{"type":"string"},"sender":{"type":"string"},"senderShort":{"type":"string"},"fee":{"type":"object","properties":{"baseUnits":{"type":"integer"},"amount":{"type":"string"},"unit":{"type":"string"}}},"confirmedRound":{"type":["integer","null"]},"timestamp":{"type":["string","null"]},"note":{"type":["string","null"]},"groupId":{"type":["string","null"]},"isGrouped":{"type":"boolean"},"receiver":{"type":["string","null"]},"receiverShort":{"type":["string","null"]},"transfer":{"type":["object","null"],"properties":{"baseUnits":{"type":"integer"},"amount":{"type":"string"},"assetId":{"type":"integer"},"assetName":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer"},"assetVerified":{"type":"boolean"},"closeRemainderTo":{"type":["string","null"]}}},"application":{"type":["object","null"],"properties":{"appId":{"type":["integer","null"]},"protocol":{"type":["string","null"]},"protocolName":{"type":["string","null"]},"component":{"type":["string","null"]},"protocolCategory":{"type":["string","null"]},"protocolVerified":{"type":"boolean"},"protocolSource":{"type":["string","null"]},"action":{"type":["string","null"]}}},"innerTransactions":{"type":"array","items":{"$ref":"#/components/schemas/DecodedTransaction"}}},"additionalProperties":true}}}}