The Walleteer Agent API enables AI agents to send USDC payments autonomously on the Solana blockchain. Agents authenticate with a per-agent API key, discover active merchants, and initiate payments within their configured spend policies.
All amounts are in USDC (6 decimal places). Balances are maintained on-chain and mirrored in the platform database.
The API is deployed on AWS Lambda (Solana devnet for staging). Mainnet deployment will use EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v as the USDC mint address.
Agent endpoints use the X-Agent-Key header. Bearer JWT authentication is used for customer-facing endpoints (balance, transaction history). Merchant discovery is open to both agent keys and unauthenticated callers.
# Obtained from POST /agents/{id}/regenerate-key or agent creation response curl https://api.walleteer.ai/agent/balance \ -H "X-Agent-Key: wlt_live_abcdef1234567890abcdef1234567890"
curl https://api.walleteer.ai/merchants \ -H "Authorization: Bearer <your_jwt>"
Returns the current USDC balance and Solana public key of the wallet owned by this agent's customer.
curl https://api.walleteer.ai/agent/balance \ -H "X-Agent-Key: wlt_live_abc123" # Response 200 { "balance": 42.500000, "currency": "USDC", "publicKey": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU" }
Returns the transaction history for this agent, ordered by most recent first. Supports optional page and pageSize query params.
curl https://api.walleteer.ai/agent/transactions?page=1&pageSize=20 \ -H "X-Agent-Key: wlt_live_abc123" # Response 200 [ { "transactionId": "a1b2c3d4-...", "status": "Completed", "corridor": "AgentToMerchant", "amount": { "amount": 10.00, "currency": "USDC" }, "feeAmount": { "amount": 0.05, "currency": "USDC" }, "netAmount": { "amount": 10.00, "currency": "USDC" }, "itemizedDetails": "order:ORD-999", "orderId": "ORD-999", "createdAt": "2026-04-14T10:00:00Z" } ]
Initiates an AgentToMerchant USDC payment on-chain. The payment is subject to the agent's active spend policy. Provide a stable idempotencyKey to safely retry on network errors.
| Field | Type | Required | Description |
|---|---|---|---|
| merchantId | uuid | ✓ | From GET /merchants |
| amount | decimal | ✓ | USDC amount (e.g. 9.99) |
| currency | string | ✓ | Must be "USDC" |
| idempotencyKey | string | ✓ | Unique per payment attempt; safe to reuse on retry |
| orderId | string | — | Your order/invoice reference; included in webhook payload |
| itemizedDetails | string | — | Free-form string, e.g. "item:SKU-1;qty:2" |
curl -X POST https://api.walleteer.ai/agent/payments/merchant \ -H "X-Agent-Key: wlt_live_abc123" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "f1a2b3c4-5678-...", "amount": 9.99, "currency": "USDC", "idempotencyKey": "ORD-999-attempt-1", "orderId": "ORD-999", "itemizedDetails": "item:PREMIUM_SKIN;qty:1" }' # Response 202 Accepted { "transactionId": "a1b2c3d4-...", "status": "Completed", "corridor": "AgentToMerchant", "createdAt": "2026-04-14T10:00:00Z" }
amount. Your wallet is debited amount + 0.05. The merchant receives the full amount.
Initiates an AgentToAgent USDC payment to another agent's wallet.
curl -X POST https://api.walleteer.ai/agent/payments/agent \ -H "X-Agent-Key: wlt_live_abc123" \ -H "Content-Type: application/json" \ -d '{ "recipientAgentId": "b2c3d4e5-...", "amount": 25.00, "currency": "USDC", "idempotencyKey": "transfer-abc-001" }' # Response 202 Accepted { "transactionId": "c3d4e5f6-...", "status": "Completed", "corridor": "AgentToAgent", "createdAt": "2026-04-14T10:01:00Z" }
When an agent successfully pays a merchant with a configured webhookUrl, Walleteer delivers a signed HTTP POST to that URL within milliseconds of on-chain settlement. Webhook delivery is fire-and-forget with a 10-second timeout.
The payload is signed with HMAC-SHA256 using the merchant's webhook secret. Always verify the signature before processing a payment notification.
{
"event": "payment.completed",
"transactionId": "a1b2c3d4-5678-90ab-cdef-...",
"agentId": "b2c3d4e5-...",
"merchantId": "f1a2b3c4-...",
"merchantCode": "GAME001",
"amount": 9.99,
"currency": "USDC",
"itemizedDetails": "item:PREMIUM_SKIN;qty:1",
"orderId": "ORD-999",
"solanaSignature": "5vLy8...Z7kp",
"timestamp": "2026-04-14T10:00:01.234Z"
}
Every delivery includes an X-Walleteer-Signature header of the form:
X-Walleteer-Signature: sha256=<hex-encoded HMAC-SHA256>
The HMAC is computed over the raw UTF-8 JSON body using the merchant's webhook secret as the key.
import hmac, hashlib def verify_signature(body: bytes, secret: str, header: str) -> bool: expected = hmac.new( secret.encode(), body, hashlib.sha256 ).hexdigest() received = header.removeprefix("sha256=") return hmac.compare_digest(expected, received) # Usage in Flask @app.route("/webhooks/walleteer", methods=["POST"]) def handle_webhook(): sig = request.headers.get("X-Walleteer-Signature", "") if not verify_signature(request.data, WEBHOOK_SECRET, sig): return "Forbidden", 403 payload = request.get_json() if payload["event"] == "payment.completed": fulfill_order(payload["orderId"], payload["amount"]) return "", 200
const crypto = require('crypto'); function verifySignature(body, secret, header) { const expected = crypto .createHmac('sha256', secret) .update(body) .digest('hex'); const received = header.replace(/^sha256=/, ''); return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(received) ); } // Express handler app.post('/webhooks/walleteer', express.raw({ type: 'application/json' }), (req, res) => { const sig = req.headers['x-walleteer-signature'] || ''; if (!verifySignature(req.body, process.env.WEBHOOK_SECRET, sig)) return res.sendStatus(403); const payload = JSON.parse(req.body); if (payload.event === 'payment.completed') fulfillOrder(payload.orderId, payload.amount); res.sendStatus(200); });
hmac.compare_digest / crypto.timingSafeEqual) to prevent timing attacks. Never compare signatures with ==.
| Status | Meaning |
|---|---|
| 400 | Bad Request — malformed JSON or missing required field |
| 401 | Unauthorized — missing or invalid X-Agent-Key / Bearer token |
| 403 | Forbidden — agent's spend policy does not allow this payment |
| 404 | Not Found — merchant, agent, or resource does not exist |
| 409 | Conflict — duplicate merchant code on creation |
| 422 | Unprocessable Entity — validation error (see errors object in response) |
| 429 | Too Many Requests — rate limit exceeded (upcoming) |
| 500 | Internal Server Error — unexpected failure; safe to retry with the same idempotencyKey |
{
"title": "One or more validation errors occurred.",
"status": 422,
"errors": {
"Amount": [ "Amount must be greater than zero." ]
}
}
All payment endpoints accept an idempotencyKey field. Submitting the same key twice returns the original transaction without re-executing the payment — safe for retries after network errors.
"ORD-999-payment")# Recommended: derive from order ID for natural idempotency idempotencyKey = f"order-{order_id}-payment" # Or generate once and persist before submitting idempotencyKey = str(uuid.uuid4())
Walleteer merchants are publicly discoverable — no authentication required. AI agents can enumerate all active merchants, read their categories and payment details, and pay them autonomously without prior integration.
Three complementary discovery surfaces exist: the standard merchant list, an /llms.txt plaintext API description, and a /.well-known/agent-skills JSON manifest. Merchants configure their public profile from the Walleteer portal.
Lists all active merchants with their public profiles and payment details. No authentication required — accessible unauthenticated, with X-Agent-Key, or Bearer JWT.
| Field | Description |
|---|---|
| merchantId | UUID — use as the payment target for POST /agent/payments/merchant |
| merchantCode | Short identifier (e.g. GAME001) — use for GET /merchants/{code} |
| name | Display name |
| category | Merchant category set in the portal (e.g. Gaming, SaaS, API) |
| description | Short public description of what the merchant sells |
| walletAddress | Solana base58 address — use as payTo for x402 payments |
| paymentInfo | Structured payment details for autonomous agent consumption |
curl https://api.walleteer.ai/merchants # Response 200 [ { "merchantId": "f1a2b3c4-5678-90ab-cdef-1234567890ab", "merchantCode": "GAME001", "name": "Acme Games", "category": "Gaming", "description": "Premium in-game skins and items for the Acme Games platform", "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "isActive": true, "paymentInfo": { "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "currency": "USDC", "howToPay": "POST /agent/payments/merchant with merchantId, or x402 via POST /agent/x402/pay with walletAddress as payTo" } } ]
Looks up a single active merchant by its unique merchantCode. Returns 404 if not found or inactive. Useful when you already know the merchant's code and want to fetch its current profile and wallet address without listing all merchants.
curl https://api.walleteer.ai/merchants/GAME001 # Response 200 { "merchantId": "f1a2b3c4-5678-90ab-cdef-1234567890ab", "merchantCode": "GAME001", "name": "Acme Games", "category": "Gaming", "description": "Premium in-game skins and items for the Acme Games platform", "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "isActive": true, "paymentInfo": { "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "currency": "USDC", "howToPay": "POST /agent/payments/merchant with merchantId, or x402 via POST /agent/x402/pay with walletAddress as payTo" } }
Returns a plaintext, machine-readable description of the Walleteer API for AI agents and LLM-based tools. Follows the emerging /llms.txt convention — agents can fetch this URL to understand the platform's capabilities, endpoints, and payment flow before interacting with the API.
curl https://api.walleteer.ai/llms.txt # Response 200 (text/plain) # Walleteer Agent API Walleteer is an AI-agent stablecoin payment platform. Agents hold USDC on Solana, discover merchants, and make payments autonomously. ## Base URL https://api.walleteer.ai ## Authentication Agent endpoints: X-Agent-Key header (wlt_live_...) Customer endpoints: Bearer JWT ## Key Endpoints GET /merchants — list all active merchants (public) GET /merchants/{code} — get a single merchant by code (public) GET /agent/balance — USDC balance for this agent's wallet POST /agent/payments/merchant — pay a merchant (AgentToMerchant) POST /agent/x402/pay — x402 payment (send signed tx to PayAI facilitator) POST /agent/x402/verify — verify an x402 payment was settled ## Payment Flow 1. GET /merchants to find a merchant and their walletAddress 2. POST /agent/x402/pay with walletAddress as payTo 3. POST /agent/x402/verify with the returned paymentSignature
Returns a structured JSON manifest of the skills this platform exposes to autonomous agents, following the /.well-known/agent-skills discovery standard. Agents and orchestration frameworks can fetch this to auto-configure themselves for merchant discovery and payment.
curl https://api.walleteer.ai/.well-known/agent-skills/index.json # Response 200 { "schema_version": "v1", "name": "Walleteer", "description": "AI agent stablecoin payment platform on Solana", "base_url": "https://api.walleteer.ai", "skills": [ { "id": "discover_merchants", "name": "Discover Merchants", "description": "List all active merchants with category, description, wallet address, and payment instructions", "method": "GET", "path": "/merchants", "auth": "none" }, { "id": "get_merchant", "name": "Get Merchant", "description": "Fetch a single merchant's full profile and payment details by merchant code", "method": "GET", "path": "/merchants/{code}", "auth": "none" }, { "id": "pay_merchant", "name": "Pay Merchant", "description": "Send a USDC payment to a merchant on Solana. Use x402 protocol for facilitator-settled payments or /agent/payments/merchant for direct Walleteer payments.", "method": "POST", "path": "/agent/x402/pay", "auth": "X-Agent-Key" } ] }
Merchant portal endpoint. Sets the public-facing category and description fields that appear in GET /merchants and GET /.well-known/agent-skills/index.json. Requires a merchant-authenticated Bearer JWT from the Walleteer portal.
| Field | Type | Required | Description |
|---|---|---|---|
| category | string | — | Free-text category visible to agents (e.g. Gaming, SaaS, API, Marketplace) |
| description | string | — | Short description of what the merchant sells; shown in agent discovery and /llms.txt |
curl -X PUT https://api.walleteer.ai/merchant/profile \ -H "Authorization: Bearer <merchant_jwt>" \ -H "Content-Type: application/json" \ -d '{ "category": "Gaming", "description": "Premium in-game skins and items for the Acme Games platform" }' # Response 204 No Content
GET /merchants and all discovery endpoints.
x402 is an open payment protocol for AI agents. Walleteer implements the x402 v2 spec, enabling any x402-compatible agent to pay Walleteer merchants directly using USDC on Solana — without prior integration or API keys from the merchant.
The flow is a two-step process:
POST /agent/x402/pay executes the on-chain USDC transfer and returns a paymentSignature.POST /agent/x402/verify confirms the payment is valid and settled. Merchants call this to gate access to their resource.Both steps require the agent's X-Agent-Key. Amounts are always in micro-USDC (6 decimal places): 1 USDC = 1000000.
| Network | Chain ID |
|---|---|
| Mainnet | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp |
| Devnet | solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 |
| Network | Mint Address |
|---|---|
| Mainnet | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |
| Devnet | 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU |
Executes an on-chain USDC transfer to the specified wallet address and returns a paymentSignature that can be passed to /agent/x402/verify. The amount is deducted from the agent's customer wallet and is subject to the agent's active spend policy.
| Field | Type | Required | Description |
|---|---|---|---|
| network | string | ✓ | CAIP-2 chain ID, e.g. "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1" |
| asset | string | ✓ | USDC SPL mint address for the target network |
| payTo | string | ✓ | Recipient Solana wallet address (base58) |
| maxAmountRequired | integer | ✓ | Amount in micro-USDC (6 decimals). 1 USDC = 1000000 |
| resource | string | ✓ | URL of the resource being purchased (for audit trail) |
| scheme | string | ✓ | Payment scheme — use "exact" |
| idempotencyKey | string | ✓ | Unique per payment attempt; safe to reuse on retry |
curl -X POST https://api.walleteer.ai/agent/x402/pay \ -H "X-Agent-Key: wlt_live_abc123" \ -H "Content-Type: application/json" \ -d '{ "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", "payTo": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "maxAmountRequired": 5000000, "resource": "https://api.acmegames.io/items/PREMIUM_SKIN", "scheme": "exact", "idempotencyKey": "x402-ORD-999-attempt-1" }' # Response 200 { "paymentSignature": "5vLy8XkP...Z7kpQmR9", "transactionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "amountPaid": 5000000 }
maxAmountRequired is in micro-USDC. 5000000 = 5.000000 USDC. The agent's wallet is debited this amount plus the 0.05 USDC platform fee. The paymentSignature is the Solana transaction signature — pass it to /agent/x402/verify.
Verifies that a prior x402 payment is valid and settled on-chain. Merchants call this endpoint (or their facilitator calls it on their behalf) to confirm payment before granting access to the purchased resource.
| Field | Type | Required | Description |
|---|---|---|---|
| paymentSignature | string | ✓ | The Solana transaction signature returned by /agent/x402/pay |
curl -X POST https://api.walleteer.ai/agent/x402/verify \ -H "X-Agent-Key: wlt_live_abc123" \ -H "Content-Type: application/json" \ -d '{ "paymentSignature": "5vLy8XkP...Z7kpQmR9" }' # Response 200 { "isValid": true, "payer": "DZnkkTmCiFWfYTfT19X5Hq9nHKMRB4mGMGbkXdmzXDFh", "transactionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }
true means the transaction exists on-chain and matches the expected recipient, amount, and asset. false means the payment cannot be verified — do not grant access to the resource.
This example shows a fully autonomous agent discovering an active merchant via GET /merchants, then completing an x402 payment and verifying it — all without prior merchant integration.
# Step 1 — Discover active merchants (no auth required) curl https://api.walleteer.ai/merchants # Response — use walletAddress as payTo, paymentInfo.network as network [ { "merchantId": "f1a2b3c4-5678-90ab-cdef-1234567890ab", "merchantCode": "GAME001", "name": "Acme Games", "category": "Gaming", "description": "Premium in-game skins and items for the Acme Games platform", "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "isActive": true, "paymentInfo": { "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "currency": "USDC", "howToPay": "POST /agent/x402/pay with walletAddress as payTo" } } ]
# Step 2 — Pay the merchant via x402 (devnet, 5 USDC) curl -X POST https://api.walleteer.ai/agent/x402/pay \ -H "X-Agent-Key: wlt_live_abc123" \ -H "Content-Type: application/json" \ -d '{ "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "asset": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", "payTo": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "maxAmountRequired": 5000000, "resource": "https://api.acmegames.io/items/PREMIUM_SKIN", "scheme": "exact", "idempotencyKey": "x402-ORD-999-attempt-1" }' # Response — save paymentSignature for the verify step { "paymentSignature": "5vLy8XkP...Z7kpQmR9", "transactionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "amountPaid": 5000000 }
# Step 3 — Verify the payment is settled (merchant or facilitator calls this) curl -X POST https://api.walleteer.ai/agent/x402/verify \ -H "X-Agent-Key: wlt_live_abc123" \ -H "Content-Type: application/json" \ -d '{ "paymentSignature": "5vLy8XkP...Z7kpQmR9" }' # Response — isValid: true means the resource can be unlocked { "isValid": true, "payer": "DZnkkTmCiFWfYTfT19X5Hq9nHKMRB4mGMGbkXdmzXDFh", "transactionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab" }
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp as the network and EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v as the asset (mainnet USDC mint).
Walleteer Agent API — Built on Solana • Powered by USDC