{"id":33285228,"url":"https://github.com/dabit3/a2a-x402-typescript","last_synced_at":"2026-01-18T08:20:27.516Z","repository":{"id":318568050,"uuid":"1071145524","full_name":"dabit3/a2a-x402-typescript","owner":"dabit3","description":"A complete TypeScript implementation of the Python x402 payment protocol extension for A2A (Agent-to-Agent) communication. Enable your AI agents to request, verify, and settle crypto payments seamlessly.","archived":false,"fork":false,"pushed_at":"2025-10-26T19:57:27.000Z","size":652,"stargazers_count":85,"open_issues_count":4,"forks_count":30,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-17T15:14:21.296Z","etag":null,"topics":["a2a","ai","ai-agents","x402"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dabit3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-06T23:43:13.000Z","updated_at":"2025-11-17T02:10:21.000Z","dependencies_parsed_at":"2025-10-08T00:36:09.802Z","dependency_job_id":null,"html_url":"https://github.com/dabit3/a2a-x402-typescript","commit_stats":null,"previous_names":["dabit3/a2a-x402-typescript"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dabit3/a2a-x402-typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dabit3%2Fa2a-x402-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dabit3%2Fa2a-x402-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dabit3%2Fa2a-x402-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dabit3%2Fa2a-x402-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dabit3","download_url":"https://codeload.github.com/dabit3/a2a-x402-typescript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dabit3%2Fa2a-x402-typescript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","ai","ai-agents","x402"],"created_at":"2025-11-17T15:09:31.299Z","updated_at":"2026-01-18T08:20:27.506Z","avatar_url":"https://github.com/dabit3.png","language":"TypeScript","funding_links":[],"categories":["🛠️ Tools \u0026 Utilities"],"sub_categories":[],"readme":"# a2a-x402\n\nA complete TypeScript implementation of the [Python x402 payment protocol extension](https://github.com/google-agentic-commerce/a2a-x402) for A2A (Agent-to-Agent) communication. Enable your AI agents to request, verify, and settle crypto payments seamlessly.\n\n[![npm version](https://badge.fury.io/js/a2a-x402.svg)](https://www.npmjs.com/package/a2a-x402)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n## Quick start\n\n```bash\nnpm install a2a-x402\n```\n\n### Basic usage\n\n#### Merchant side (request payment)\n\n```typescript\nimport { x402PaymentRequiredException } from 'a2a-x402';\n\n// In your agent tool, throw an exception to request payment:\nthrow new x402PaymentRequiredException(\n  \"Payment required for product\",\n  {\n    scheme: \"exact\",\n    network: \"base-sepolia\",\n    asset: \"0x036CbD53842c5426634e7929541eC2318f3dCF7e\", // USDC\n    payTo: \"0xYourWalletAddress\",\n    maxAmountRequired: \"1000000\", // 1 USDC in atomic units\n    resource: \"/buy-product\",\n    description: \"Payment for banana\",\n    mimeType: \"application/json\",\n    maxTimeoutSeconds: 1200,\n  }\n);\n```\n\n#### Client side (process payment)\n\n```typescript\nimport { processPayment, x402Utils } from 'a2a-x402';\nimport { Wallet } from 'ethers';\n\nconst wallet = new Wallet(privateKey);\nconst utils = new x402Utils();\n\n// Get payment requirements from task\nconst paymentRequired = utils.getPaymentRequirements(task);\n\n// Sign the payment\nconst paymentPayload = await processPayment(\n  paymentRequired.accepts[0],\n  wallet\n);\n```\n\n## Features\n\n- **Exception-based payment flow** - Throw exceptions to request payments dynamically\n- **Full TypeScript support** - Complete type definitions and interfaces\n- **Ethereum wallet integration** - Built on ethers.js for signing and verification\n- **Dynamic pricing** - Set prices based on request parameters\n- **Multi-network support** - Works with Base, Base Sepolia, and other EVM chains\n- **ERC-20 token payments** - Native support for USDC and other tokens\n- **ADK-compatible** - Works seamlessly with [ADK TypeScript](https://github.com/njraladdin/adk-typescript)\n\n## What's included\n\nThe library provides a complete implementation of the x402 payment protocol:\n\n### Core modules\n\n- **Payment requirements** - Create and validate payment requests\n- **Wallet integration** - Sign and process payments with ethers.js\n- **Protocol verification** - Verify signatures and settle transactions\n- **State management** - Track payment status and metadata\n- **Utility functions** - Helper functions for common operations\n\n### Optional executors\n\nAbstract base classes for building payment-enabled agents:\n- `x402ServerExecutor` - For merchant/service provider agents\n- `x402ClientExecutor` - For client/wallet agents\n\n## API reference\n\n### Core functions\n\n#### `x402PaymentRequiredException`\n\nThe main exception class for requesting payments:\n\n```typescript\n// Simple payment request\nthrow new x402PaymentRequiredException(\n  \"Payment required\",\n  {\n    scheme: \"exact\",\n    network: \"base-sepolia\",\n    asset: \"0x036CbD53842c5426634e7929541eC2318f3dCF7e\",\n    payTo: \"0xYourAddress\",\n    maxAmountRequired: \"1000000\",\n    resource: \"/service\",\n    description: \"Service payment\",\n    mimeType: \"application/json\",\n    maxTimeoutSeconds: 1200,\n  }\n);\n\n// Multiple payment options\nthrow new x402PaymentRequiredException(\n  \"Choose payment tier\",\n  [basicTier, premiumTier, ultraTier]\n);\n```\n\n#### `processPayment()`\n\nSign a payment with a wallet:\n\n```typescript\nimport { processPayment } from 'a2a-x402';\nimport { Wallet } from 'ethers';\n\nconst wallet = new Wallet(privateKey);\nconst paymentPayload = await processPayment(requirements, wallet);\n```\n\n#### `x402Utils`\n\nUtility class for managing payment state:\n\n```typescript\nimport { x402Utils } from 'a2a-x402';\n\nconst utils = new x402Utils();\n\n// Get payment status\nconst status = utils.getPaymentStatus(task);\n\n// Get payment requirements\nconst requirements = utils.getPaymentRequirements(task);\n\n// Record payment success\nutils.recordPaymentSuccess(task, settleResponse);\n```\n\n### Abstract executors\n\n#### `x402ServerExecutor`\n\nBase class for merchant agents:\n\n```typescript\nimport { x402ServerExecutor } from 'a2a-x402';\n\nclass MyMerchantExecutor extends x402ServerExecutor {\n  async verifyPayment(payload, requirements) {\n    // Verify signature and payment details\n  }\n\n  async settlePayment(payload, requirements) {\n    // Execute on-chain settlement\n  }\n}\n```\n\n#### `x402ClientExecutor`\n\nBase class for client agents:\n\n```typescript\nimport { x402ClientExecutor } from 'a2a-x402';\n\nclass MyClientExecutor extends x402ClientExecutor {\n  async handlePaymentRequired(error, task) {\n    // Process payment requirements\n  }\n}\n```\n\n## Example implementations\n\nThis repository includes two fully functional example agents that demonstrate end-to-end payment flows:\n\n### Client agent\n\nA payment-enabled orchestrator agent that can interact with merchants and process payments.\n\n**Install and run:**\n```bash\ncd client-agent\nnpm install\ncp .env.example .env\n# Edit .env with your API keys and wallet\nnpm run dev\n```\n\n**Features:**\n- Secure wallet with ERC-20 support\n- Automatic USDC approvals\n- Natural language purchase requests\n- User confirmation flows\n\nSee [client-agent/README.md](client-agent/README.md) for details.\n\n### Merchant agent\n\nA service provider agent that requests payments, verifies signatures, and settles transactions.\n\n**Install and run:**\n```bash\ncd merchant-agent\nnpm install\ncp .env.example .env\n# Edit .env with your API keys and wallet\nnpm run dev\n```\n\n**Features:**\n- Dynamic pricing\n- Payment verification\n- Order fulfillment\n- Secure settlement\n\nSee [merchant-agent/README.md](merchant-agent/README.md) for details.\n\n### Full demo\n\nRun both agents to see the complete payment flow:\n\n**Terminal 1 - Merchant:**\n```bash\ncd merchant-agent \u0026\u0026 npm run dev\n```\n\n**Terminal 2 - Client:**\n```bash\ncd client-agent \u0026\u0026 npm run dev\n```\n\n**Client terminal:**\n```\nYou: I want to buy a banana\nAgent: The merchant is requesting 1.000000 USDC for a banana. Proceed?\nYou: yes\nAgent: Payment completed! Transaction: 0x...\n```\n\n## Development\n\n### Local development\n\nIf you want to modify the library locally and test with your agents:\n\n```bash\n# Clone and build the library\ngit clone \u003crepo-url\u003e\ncd a2a-x402-typescript/x402_a2a\nnpm install\nnpm run build\n\n# Link for local development\ncd ../your-project\nnpm install a2a-x402\n```\n\n### Testing\n\nThe example agents include test scripts:\n\n```bash\n# Test merchant payment flow\ncd merchant-agent\nnpm run test:payment\n\n# Test client agent\ncd client-agent\nnpm run dev\n```\n\n## Supported networks\n\nThe library works with any EVM-compatible network. The example agents use:\n\n### Base Sepolia (testnet)\n- Chain ID: `84532`\n- RPC: `https://sepolia.base.org`\n- USDC: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`\n- Explorer: https://sepolia.basescan.org/\n- Faucets:\n  - ETH: https://www.alchemy.com/faucets/base-sepolia\n  - USDC: https://faucet.circle.com/\n\n### Base Mainnet (production)\n- Chain ID: `8453`\n- RPC: `https://mainnet.base.org`\n- USDC: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`\n- Explorer: https://basescan.org/\n\n## Security\n\n### Best practices\n\n**Private key management:**\n- Never commit private keys or `.env` files\n- Use separate wallets for testing and production\n- Keep minimal balances in hot wallets\n- Consider hardware wallets for production\n\n### Token approvals\n\nThe example client agent uses a 10% buffer for approvals:\n```typescript\nconst approvalAmount = (amount * 110n) / 100n;\n```\n\nAlways review approval amounts before signing transactions.\n\n## Additional resources\n\n### Documentation\n- [Client agent README](client-agent/README.md) - Wallet agent implementation details\n- [Merchant agent README](merchant-agent/README.md) - Service provider implementation\n- [Deployment guide](merchant-agent/DEPLOYMENT.md) - Production deployment instructions\n\n### Related projects\n- [ADK TypeScript](https://github.com/njraladdin/adk-typescript) - Agent Development Kit for TypeScript\n- [Python x402 implementation](https://github.com/google-agentic-commerce/a2a-x402) - Original protocol specification\n\n## License\n\nApache-2.0 - See [LICENSE](LICENSE) for details\n\n## Getting started\n\n1. Install the package: `npm install a2a-x402`\n2. Try the examples: Run the client and merchant agents\n3. Build your agent: Use the library in your own project\n4. Customize: Adapt the example agents to your needs\n\n## Contributing\n\nContributions welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdabit3%2Fa2a-x402-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdabit3%2Fa2a-x402-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdabit3%2Fa2a-x402-typescript/lists"}