xagent-pay-api

XAgent Pay API XRPL Payment API for AI Developers ## Introduction API-based XRPLRP Ledger) testnet that abstracts away complex blockchain logic, allowing AI agents and applications to easily integrate XRP and RLUSD payments. - **Supported Currencies:** XRP, RLUSD (stablecoin) - **Authentication:** Issuable/revocable API keys, tiered fees and limits - **Wallet:** Automatically generated and funded XRPL wallet for each API key (separate operation for each agent) - **Monitoring:** Usage dashboard (web UI), transaction history, and accumulated fees - **Notifications:** Webhook callbacks for payment success/failure (with signature verification and retries) ## Quick Start ```bash # 1. Clone repository & install dependencies pip install -r requirements.txt # 2. Create .env file (copy from .env.example and fill in values) cp .env.example .env ``` You must fill in at least the following values in `.env server to start: SENDER_ADDRESS_XRP_address # platform shared wallet (for legacy key fallback) SENDER_SECRET=secret_key FEE_ACCOUNT=fee_receiving_address XRPL_NODE=wss://s.altnet.rippletest.net:51233 ADMIN_API_KEY=strong_admin_key # for issuing/revoking API keys (disable /admin/keys if not set) you don't have a account, get one fromXRPL Faucet](https://xrpl.org-testnet-faucet```bash # Run server python main.py # or uvicorn main:app --host 0.0.0.0 --port 8000 (but see "known limitations" below — currently designed for single worker) uvicorn main:app --host 0..0 --port 8000 --workers 1 ``` - API: http://localhost:8000 - Swagger documentation: http://localhost:8000/docs - Usage dashboard: http://localhost:8000/dashboard ```bash # 4. Issue first API key (run once with admin key) curl -X POST "http://localhost:8000/admin/keys" \ -H "Content-Type: application/json" \ -H "X-Admin-Key: your_admin_key" \ -d '{"name": "my-first-agent", "tier": "free"}' ``` The `api_key` in the response is the `X-API-Key` value to use for all subsequent requests. **Keep it secure**, as it can only be viewed in plain text in this response. The `wallet_address` in the same response is the automatically generated and funded wallet address for this key. ## Pricing Tier | Price | Monthly Request Limit | Payment Fee Rate---|---|---|---| | Free | $0 | 100 1% | | Pro | $49/month | Unlimited | 0.15% | | Enterprise | Custom | Unlimited | Custom (negotiable based on volume) | - The $49/month subscription fee for Pro is not handled directly by this API (handled by a separate SaaS layer). - This API only applies a **fee rate per payment transaction**, which is determined by the tier. - For Enterprise, you can specify a custom `fee_rate` when issuing the key to override the tier's default. ## Authentication — API Key Issuance, Query, and Revocation Admin operations (issuing, revoking) require the `X-Key` header all other API operations use the issued `X-API-Key` header. ```bash # Issue key (includes auto-generation of dedicated wallet) curl -X POST "http://localhost:8000/admin/keys" -H "Content-Type: application/json" \ -H "X-Admin-Key: your_admin_key" \ d '{"name": "customer-a-bot", "tier": "pro"}' # (plaintext keys not exposed) curl "http://localhost:8000/admin/keys" -H "X-Admin your_admin_key" oke key curl -X POST "http://localhost0/admin/keys/{key_id}/revoke" \ -H "X-Admin-Key: your_admin_key| Code | Description | | | No API key provided | 403 | API key is invalid or revoked | | | Tier's monthly limit 503 |_API_KEY` not set admin API | ## Wallet Management (Multi-Agent) When key is issued, a **dedicated wallet is automatically generated and funded** using the XRPL testnet faucet. Subsequent payments made with this key will this **dedicated not the platform's shared allowing multiple agents to without conflicts. ```bash "http://localhost0/wallet/infoH "X-API-Key_api_key" ``` ```json { "walletr...", _xrp": 5, "ded true } ``` dedicated: false`, it means the dedicated wallet generation failed (e.g to testnet faucet rate limits) or the key was `.env`'s `API_KEYS` as a legacy key, sharing the platform's shared wallet. ## Payment API payment APIs require the-Key` header Create Payment **X:** ```bash curl -X POST "http://8000/payment/create" \ -H ": application/json" \ H "X-API_api_key" \ -d '{ "recipient_address": "rExampleAddress...", "amount": 10.0, "currency": "XRP" }' ``` **RLUSD Payment:** ```bash curl -X POST "http://localhost:8000/payment/create" \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key" \ -d '{ _address": "Address...", "amount100.0, currency": "RL }' ``` ⚠️ **RLUSD Payment Precaution:** The recipient must first set up a trust line for the RLUSD token. ** (fee rate depends on the API key tier — Pro tier example below) ```json "success": true, "tx_hash": "transaction_hash", "fee_amount": 0. "fee_rate": 0.0015, "sent_amount": 9.985, "remaining_quota": null Verify/Check ```bash curl "http://localhost:8000/payment/verify/{tx_hash}" -H "X-API-Key: your_api_key" curl "http://localhost:8000/payment/status/{tx_hash}" -H "X-API-Key: your_api_key" ``` ### Check Supported Currencies and Fee Rates (no authentication required) ```bash curl "http://localhost:8000ates" ``` ```{ "supported_currencies": { RP": {"currencyXRP", "issuer, "scale": 6}, "RLUSD": {"currency": "RLUSD", "issuer": "rMxCKbEDwqr76QuheSUMdEGf4B9x5De",": 5} "default_currency":RP", "fee_rates_by_tier": {"free": 0.01, "pro": 05, "enterprise.0015} } ``` ## Usage Dashboard http://localhost:/dashboard in your browser, enter your API key, and tier, request count quota, accumulated fees transactions, wallet address, and balance. You can also query this data via API: ```bash # quota + accumulated fees + recent transactions (same data as dashboard page) curl "http://localhost:8000/usage/dashboard" -H "X-API-Key: your_api_key" # transactions only curl "http://localhost:8000/usage/transactions?limit=50" -H "X-API-Key: your_api_key" # quota only curl "http://localhost:8000/usage/info" -H "X: your_api``` ## Rate Limit- **Free:** Too Many Requests` if100 requests/month Pro / Enterprise:**no request limit, charged by fees) - Limit adjusted via the `FREE_MONTHLY_LIMIT` environment variable ## Webhook Notifications Send events to a specified URL on payment success (`payment.success`) or failure (`payment.failed`). If payment fails, retry 3 times with 2, 10, and 60-second intervals. ```bash # Register (a new signing secret is generated for each registration, only viewable in this response) curl -X PUT "http://localhost:800hook" \ "Content-Type: application/json" \ -X-API-Key: your_api_key" \ '{"url": "your-server.com/xhook"}' # Query curl "http://localhost:8000/webhook" -H "X-API-Key: your_api_key" # Delete curl -X DELETE "http://localhost:8000/webhook" -H "X-API-Key: your_api_key" ``` Verify the signature on the receiving server: ```python import hmac, hashlib expected = hmac.new(webhook_secret.encode(), request_body, hashlib.sha256).hexdigest() is_valid = hmac.compare, received_signature.remrefix("sha256=")) ``` Internal/private IPs, company network, etc.) cannot be registered as webhook prevent SSRF. ## x402 Payment Standard support for HTTP 402 Payment Required for AI agents ```bash # 1. Request resource that requires payment curl "http://localhost0/data/market-info" # → 402 + payment info header 2. Create payment curl -X POST "http://localhost0/x402/create \ -H-API-Key: your_api_key" # 3. Issue access token curl -X POST "http://localhost:8000/x402 \ -H "Content-Type: application/json" \ -d '{"tx_hash": "transaction_hash"}' # 4. Access resource with token curl "http://localhost:8000/data/market-info" \ -H "X-Payment-Token_token" ``` USD Trust Line ### What Trust Line? is a limit that must be set on the XRPL to send and receive IOU tokens (e.g., RLUSD). ### How to Set Up a Trust Line 1. Using Wallet (recommended) . Access Xamanhttps://xaman.app) 2. Set testnet → "I want to add a trust line" 3. Enter info: : USD uer: rMxEDwqr76QudEGf9xJ8De 4. Set trust line limit (e.g., 1000) 5 and set up#### 2. Using XRPL Explorer ``` 1. Access XRPL Test (https://testnet.xrpl.org) 2. Search for wallet address 3. "Trust Lines → "Add Trust4. Currency: Issuer: rbEDwqr76QuheSUMdEGf4B9xJ5De 5 limit and add Verify Trust Line ```bash curl "localhost:8000ustline/{address}" \ -H "X-API-Key_api_key" ``` (no trust line):** ```json "address":ExampleAddress "has_rlUSD_trustline": false, "rlUSD_limit": null, "rlUSD_balance": null, "message": "RLUSD trust line is not set up." } ``` ### Error Handling Without Trust Line If the recipient hasn't set up a trust line for RLUSD payments, an error will be returned: ```json { "detail": "The recipient has not set up a trust line for the RLUSD token. The recipient must set up a trust line to receive." } ``` **Solution:** Share this trust line setup guide with the recipient and have them set up the trust line. ## Claude MCP Integration Claude AI can directly call the XAgent Pay API as a tool. ### Installation and Execution ```bash # Start XAgent Pay API server python main.py # Start MCP server (separate terminal) python mcp_server.py ``` Specify the API key for MCP in `.env`: ```bash MCP_API_KEY=your_api_key ``` ### Claude Desktop Configuration **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%/Claude/claude_desktop_config.json` ```json { "mcpServers": { "xagent-pay-api": { "command": "python", "args": ["/path/to/mcp_server.py"], "env": { "XAGENT_PAY_API_URL": "http://localhost:8000", "MCP_API_KEY": "your_api_key" } } } } ``` ### Available Tools - **get_rates** — Check supported currencies and fees - **create_payment** — Create XRP/RLUSD payment - **verify_payment** — Verify transaction - **check_trustline** — Check RLUSD Trust Line ### Demo Actual result of Claude AI sending 1 XRP: - Recipient address: rM9SpkNUPUygwTcE7baTYTe6BwhKe- Actual amount sent: 0.99 XRP - Fee: 0.01 XRP (1%) - TX hash: CB2AC710B2EA8E335FB7EBEB258306CE96C30C0F09ABD728087C6099AC28D9AB ## Roadmap - [x] x402 token- [x] (stablecoin) support - [x] MCP server support (Claude AI integration) - [x] Issuable/revocable API keys + tiered authentication - [x] Usage dashboard - [x] Rate limiting + multi-wallet management - [x] Webhook notifications - [ ] Additional IOU token support - [ ] Mainnet deployment - [ ] Batch payments ## Known Limitations - Currently, API key/transaction/webhook settings are stored in a JSON file. Designed for single process (`--workers 1`), scaling to/instances requires migration to SQLite, etc. (see [TODO_MIGRATION.md](TODO_MIGRATION.md) for details). - Currently for testnet only. Additional security review required for mainnet deployment. ## Security - **Dedicated wallet seeds are encrypted with `SECRET_ENCRYPTION_KEY` (Fernet) and stored**. Without, dedicated wallet generation is disabled (preventing plaintext storage). Never hardcode the master key in code; manage it only with `. The `SENDER (platform shared wallet) in `.env still in plaintext — necessary bootstrap credentials outside the app scope. Consider/Secrets Manager mainnet deployment. ⚠️ **Currently for only**. For mainnet usage, review: - Migrate API key/admin key storage to SQLite, etc., and strengthen access control - Enhance SSRF prevention logic for webhook URLs (currently blocking private/loopback IPs) ## License MIT License ## GitHub Repository This project is managed on GitHub. Report bugs and feature requests via Issues. --- Inquiries: [GitHub Issues](https://github.com/TLSRUF/xagent-pay-api/issues)