agentwallet

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: agentwallet
version: 0.2.0
description: Wallets for AI agents with x402 and MPP payment signing, referral rewards, and policy-controlled actions.
homepage: https://frames.ag
metadata: {"moltbot":{"category":"finance","api_base":"https://frames.ag/api"},"x402":{"supported":true,"chains":["solana","evm"],"networks":["eip155:1","eip155:8453","eip155:10","eip155:137","eip155:42161","eip155:56","eip155:11155111","eip155:84532","eip155:100","solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"],"tokens":["USDC","USDT","CASH"],"endpoint":"/api/wallets/{username}/actions/x402/fetch","legacyEndpoint":"/api/wallets/{username}/actions/x402/pay"},"mpp":{"supported":true,"methods":["tempo"],"endpoint":"/api/wallets/{username}/actions/mpp/pay"},"referrals":{"enabled":true,"endpoint":"/api/wallets/{username}/referrals"}}
---

# AgentWallet

AgentWallet provides server wallets for AI agents. Wallets are provisioned after email OTP verification. All signing happens server-side and is policy-controlled.

---

## TL;DR - Quick Reference

**FIRST: Check if already connected** by reading `~/.agentwallet/config.json`. If file exists with `apiToken`, you're connected - DO NOT ask user for email.

**Need to connect (no config file)?** Ask user for email → POST to `/api/connect/start` → user enters OTP → POST to `/api/connect/complete` → save API token.

**x402 Payments?** Use the ONE-STEP `/x402/fetch` endpoint (recommended) - just send target URL + body, server handles everything.

---

## x402/fetch - ONE-STEP PAYMENT PROXY (RECOMMENDED)

**This is the simplest way to call x402 APIs.** Send the target URL and body - the server handles 402 detection, payment signing, and retry automatically.

```bash
curl -s -X POST "https://frames.ag/api/wallets/USERNAME/actions/x402/fetch" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://registry.frames.ag/api/service/exa/api/search","method":"POST","body":{"query":"AI agents","numResults":3}}'
```

**That's it!** The response contains the final API result:

```json
{
  "success": true,
  "response": {
    "status": 200,
    "body": {"results": [...]},
    "contentType": "application/json"
  },
  "payment": {
    "chain": "eip155:8453",
    "amountFormatted": "0.01 USDC",
    "recipient": "0x..."
  },
  "paid": true,
  "attempts": 2,
  "duration": 1234
}
```

### x402/fetch Request Options

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Target API URL (must be HTTPS in production) |
| `method` | string | No | HTTP method: GET, POST, PUT, DELETE, PATCH (default: GET) |
| `body` | object | No | Request body (auto-serialized to JSON) |
| `headers` | object | No | Additional headers to send |
| `preferredChain` | string | No | `"auto"` (default), `"evm"`, or `"solana"`. Auto selects chain with sufficient balance |
| `preferredToken` | string | No | Token symbol to pay with: `"USDC"` (default), `"USDT"`, `"CASH"`. Uses first available if not specified |
| `dryRun` | boolean | No | Preview payment cost without paying |
| `timeout` | number | No | Request timeout in ms (default: 30000, max: 120000) |
| `idempotencyKey` | string | No | For deduplication |
| `walletAddress` | string | No | Wallet address to use (for multi-wallet users). Omit to use default wallet. |

### Dry Run (Preview Cost)

Add `"dryRun": true` to the request body. Returns payment details without executing:

```json
{
  "success": true,
  "dryRun": true,
  "payment": {
    "required": true,
    "chain": "eip155:8453",
    "amountFormatted": "0.01 USDC",
    "policyAllowed": true
  }
}
```

### Error Codes

| Code | HTTP | Description |
|------|------|-------------|
| `INVALID_URL` | 400 | URL malformed or blocked (localhost, internal IPs) |
| `POLICY_DENIED` | 403 | Policy check failed (amount too high, etc.) |
| `WALLET_FROZEN` | 403 | Wallet is frozen |
| `TARGET_TIMEOUT` | 504 | Target API timed ou