{
  "markdown": "# tx402\n\nPlain-English explanations of Algorand transactions, sold as a pay-per-call API\nwith x402 on Algorand.\n\nLive service:\n\n```text\nhttps://tx402-production.up.railway.app\n```\n\nExplain one transaction, every leg of an atomic group, a batch of IDs, or recent\naccount activity. Responses include scaled amounts, inner transactions, asset\nnames, fees, timestamps, counterparties, and source-verified protocol labels.\n\nTry the free fixed-transaction demo without a wallet:\n\n```text\nhttps://tx402-production.up.railway.app/demo?example=algo\n```\n\n```http\nGET /explain?txid=YRSG7IKDPCK4XMKFFTFFFYMIHF6SJOMHUOIE4FFUWNLEQ4WG2ZOQ\n```\n\nExample response after payment:\n\n```json\n{\n  \"txid\": \"YRSG7IKDPCK4XMKFFTFFFYMIHF6SJOMHUOIE4FFUWNLEQ4WG2ZOQ\",\n  \"network\": \"mainnet\",\n  \"summary\": \"On June 16, 2019, wallet VCINCV...JPMIPM sent 1 ALGO to CRBMB5...QLXZOY. Paid 0.001 ALGO in fees.\",\n  \"details\": {\n    \"type\": \"pay\",\n    \"sender\": \"VCINCVUX2DBKQ6WP63NOGPEAQAYGHGSGQX7TSH4M5LI5NBPVAGIHJPMIPM\",\n    \"transfer\": {\n      \"amount\": \"1\",\n      \"assetId\": 0,\n      \"unit\": \"ALGO\"\n    }\n  }\n}\n```\n\nRaw Algorand indexer JSON is optimized for machines doing bookkeeping: amounts\nare base units, assets are numeric IDs, and notes are base64. tx402 is the\ntranslation layer for agents and applications that need to explain a transaction\nto a person.\n\n## API\n\nPublic routes:\n\n- `GET /` - landing page with service metadata links\n- `GET /health` - process liveness\n- `GET /health?deep=1&network=mainnet` - readiness check for upstream services\n- `GET /discovery` - machine-readable service description and pricing metadata\n- `GET /openapi.json` - OpenAPI 3.1 specification\n- `GET /.well-known/agent.json` - agent marketplace manifest\n- `GET /.well-known/x402` - x402 resource manifest\n- `GET /llms.txt` - agent-readable documentation\n- `GET /demo?example=algo|usdc` - free allowlisted Mainnet examples\n- `GET /explain?txid=...&network=mainnet` - paid transaction explanation\n- `GET /group?txid=...&network=mainnet` - paid atomic-group explanation\n- `POST /batch` - paid batch of 1 to 10 transaction IDs\n- `GET /account/activity?address=...&limit=25` - paid activity summary\n- `GET /analytics` - free aggregate adoption counters\n\nDefault prices are `$0.005` for `/explain`, `$0.01` for `/group`, `$0.02` for\n`/batch`, and `$0.01` for `/account/activity`. Production accepts Mainnet USDC:\n\n- network: `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=`\n- asset: `31566704`\n- receiver: `6RK3U3OF2B4Q773L4KC7OVFHQGU5I74NHRZ36QN6CVF527CKXAL62YR754`\n\n## Architecture\n\ntx402 has a small deterministic core and a thin serving shell.\n\nCore:\n\n- [src/decoder.js](./src/decoder.js) converts raw Algorand indexer JSON into a\n  normalized transaction object.\n- [src/narrator.js](./src/narrator.js) converts that normalized object into one\n  readable sentence.\n- [src/insights.js](./src/insights.js) builds group and account-level summaries.\n- [src/explainer.js](./src/explainer.js) resolves assets and orchestrates the\n  single, group, batch, and account products.\n- [src/knownApps.js](./src/knownApps.js) maps known app and asset IDs to human\n  labels with a verification source for every narrated protocol claim.\n\nServing shell:\n\n- [src/index.js](./src/index.js) owns HTTP routes, middleware ordering, logging,\n  rate limits, health checks, and graceful shutdown.\n- [src/indexer.js](./src/indexer.js) is the only module that talks to AlgoNode's\n  public indexer.\n- [src/payments.js](./src/payments.js) declares the x402 price and receiver, then\n  delegates verification and settlement to the hosted GoPlausible facilitator.\n- [src/rateLimit.js](./src/rateLimit.js) provides the in-memory per-IP limiter.\n- [src/analytics.js](./src/analytics.js) keeps aggregate process-local adoption\n  counters without cookies, raw wallet addresses, query strings, or IP history.\n\nThe server never stores private keys. Buyer signing happens client-side. The\nresource server only advertises a price, validates payment, and settles through\nthe facilitator after a successful product-route response.\n\n## Run Locally\n\n```bash\nnpm install\nnpm start\nnpm test\n```\n\nLocal endpoints:\n\n```bash\ncurl \"http://localhost:4021/health\"\ncurl \"http://localhost:4021/discovery\"\ncurl \"http://localhost:4021/explain?txid=SOME_REAL_MAINNET_TXID\"\ncurl \"http://localhost:4021/group?txid=SOME_REAL_MAINNET_TXID\"\n```\n\nThe app reads `.env` when present. Leave `USDC_ASSET_ID` unset unless you need a\nnon-standard asset; the code derives the canonical USDC asset from `NETWORK`.\n\n## Client Examples\n\nRead-only example client:\n\n```bash\nnpm run example:client\nnpm run example:catalog\n```\n\nThe default client prints discovery metadata and the x402 payment challenge\nwithout spending funds. To make it pay, configure a funded buyer wallet and set\n`TX402_EXAMPLE_PAY=1` plus `CONFIRM_MAINNET_PAYMENT=1`.\n\nOpenAPI:\n\n- [openapi.json](./openapi.json)\n- `https://tx402-production.up.railway.app/openapi.json`\n\nAgent marketplace metadata:\n\n- `https://tx402-production.up.railway.app/.well-known/agent.json`\n- `https://tx402-production.up.railway.app/.well-known/x402`\n- `https://tx402-production.up.railway.app/llms.txt`\n\nCopy-paste integrations and distribution assets:\n\n- [Integration guide](./docs/INTEGRATIONS.md)\n- [Distribution checklist](./docs/DISTRIBUTION.md)\n- [GoPlausible MCP proposal](./docs/GOPLAUSIBLE_PROPOSAL.md)\n- [Outreach kit](./submission/outreach-kit.md)\n\nThe paid route also declares the standard x402 Bazaar extension, including its\ninput/output schemas, service metadata, and example request. Facilitators can\nindex that metadata after a successful settlement.\n\nMCP wrapper:\n\n```bash\nnpm run mcp\n```\n\nAfter the public npm package is published, agents can install it without\ncloning this repository:\n\n```bash\nnpx tx402-mcp\n```\n\nBy default the MCP wrapper is read-only and returns x402 payment requirements\nfor paid calls. To let it pay from a local wallet, set\n`TX402_MCP_ENABLE_PAYMENTS=1` and `CONFIRM_MAINNET_PAYMENT=1`.\n\nThe six-part adoption roadmap is tracked in [PLAN.md](./PLAN.md).\n\n## Submission Assets\n\n- [Pitch deck](./submission/pitch-deck.md)\n- [Demo video script](./submission/demo-video-script.md)\n\n## Security Notes\n\n- Output strings can contain untrusted on-chain data, including asset names and\n  notes. JSON output is safe as JSON, but consumers rendering HTML must escape it.\n- Invalid `txid` input is rejected before indexer access and before payment.\n- Payment only settles after a successful response.\n- All product routes, `/analytics`, `/discovery`, and deep health checks are rate-limited.\n- Protocol/app names are only stated as fact when marked `verified: true`.\n- Application logs omit query strings and client IP addresses.\n\n## Status\n\n- [x] Phase 1 - core explainer, free and local\n- [x] Phase 2 - x402 payment middleware on Testnet, verified end-to-end\n- [x] Phase 3 - public HTTPS deployment\n- [x] Phase 4 - Mainnet payment configuration\n- [x] Phase 5 - first real Mainnet settlement\n- [x] Phase 6 - example client, OpenAPI spec, optional MCP wrapper\n\nFirst Mainnet settlement:\n\n- txid: `XA7HMRPUV4X2GWI4AAGUT5FKAVTNCQJ5ZMUNTVTBKG3GZMES27LA`\n- amount: `0.005000` USDC\n\n## Maintainer Notes\n\nImplementation runbooks, deployment commands, phase evidence, and operational\ncautions live in [CLAUDE.md](./CLAUDE.md).\n",
  "bytes": 7286,
  "sha": "728955752e3347a8b603502bcf4dcca66707a8f704017a07dc2447c69190afa7",
  "repo_slug": "mahesvannan/tx402",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mahesvannan_tx402_e3c6a533/readme"
}