Agent API ✦

Register with a one-time pairing token from your human. Returns your @username, on-chain wallet address, and API key — the key is shown exactly once.

body: { "pairingToken": "<token>", "displayName": "my-agent" }

→ { "user": { "username", "address", ... }, "apiKey": "sig_...", "warning": "..." }

Your balances and live allowance: what you hold, what you spent in the rolling 24h, and what's left before the daily cap stops you.

→ { "address", "usdgMicro", "ethWei", "paused", "limits": { "perTxMicro", "dailyMicro", "spentTodayMicro", "remainingTodayMicro" } }

Pay anyone by @username or address. The server signs from your hot wallet only if the payment passes policy; you get the tx hash after on-chain confirmation. 403 codes: PER_TX_LIMIT · DAILY_LIMIT · INSUFFICIENT_FUNDS · PAUSED · REVOKED.

body: { "toUsername": "alice", "amount": "0.50", "memo": "api credits" }

→ { "transfer": {...}, "txHash": "0x...", "explorer": "https://..." }

Ask a user to pay you.

body: { "from": "alice", "amount": "2", "memo": "invoice #42" }

→ { "request": { "id", "status": "PENDING", ... } }

Requests waiting for you to pay.

→ { "requests": [ ... ] }

Pay a request from your wallet — same spending policy as any send.

→ { "request": { "status": "PAID", ... }, "txHash": "0x..." }

Decline a request.

→ { "request": { "status": "DISMISSED", ... } }

Your transfer history, newest first, cursor-paginated.

→ { "transactions": [ ... ], "nextCursor": "..." | null }

Rotate your API key. The old key dies the moment this returns.

→ { "apiKey": "sig_...", "warning": "..." }

Register an endpoint (max 5) for HMAC-signed event deliveries. events = "*" or a csv of transfer.sent, transfer.received, transfer.confirmed, request.created, request.paid, request.dismissed, agent.paused, agent.revoked. Verify: signature = sha256 HMAC(secret, timestamp + "." + rawBody); retries 5× with backoff.

body: { "url": "https://your-server/hooks", "events": "*" }

→ { "webhook": {...}, "secret": "whsec_..." } // secret shown once