agentwallet-framesWallets for AI agents with x402 payment signing, referral rewards, and policy-controlled actions.
Install via ClawdBot CLI:
clawdbot install microchipgnu/agentwallet-framesAgentWallet provides server wallets for AI agents. Wallets are provisioned after email OTP verification. All signing happens server-side and is policy-controlled.
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.
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.
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://enrichx402.com/api/exa/search","method":"POST","body":{"query":"AI agents","numResults":3}}'That's it! The response contains the final API result:
{
"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
}| 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 USDC balance |
| dryRun | boolean | No | Preview payment cost without paying |
| timeout | number | No | Request timeout in ms (default: 30000, max: 120000) |
| idempotencyKey | string | No | For deduplication |
Add "dryRun": true to the request body. Returns payment details without executing:
{
"success": true,
"dryRun": true,
"payment": {
"required": true,
"chain": "eip155:8453",
"amountFormatted": "0.01 USDC",
"policyAllowed": true
}
}| 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 out |
| TARGET_ERROR | 502 | Target API returned 5xx error |
| PAYMENT_REJECTED | 402 | Payment was rejected by target API |
| NO_PAYMENT_OPTION | 400 | No compatible payment network |
Store credentials at ~/.agentwallet/config.json:
{
"username": "your-username",
"email": "your@email.com",
"evmAddress": "0x...",
"solanaAddress": "...",
"apiToken": "mf_...",
"moltbookLinked": false,
"moltbookUsername": null,
"xHandle": null
}| Field | Description |
|-------|-------------|
| username | Your unique AgentWallet username |
| email | Email used for OTP verification |
| evmAddress | EVM wallet address |
| solanaAddress | Solana wallet address |
| apiToken | Fund API token for authenticated requests (starts with mf_) |
| moltbookLinked | Whether a Moltbook account is linked |
| moltbookUsername | Linked Moltbook username (if any) |
| xHandle | X/Twitter handle from Moltbook (if linked) |
Security: Never commit to git. Set chmod 600. Treat apiToken like a password.
Web flow: Ask user for email → direct to https://frames.ag/connect?email=EMAIL → user enters 6-digit OTP → page displays credentials (AGENTWALLET_USERNAME, AGENTWALLET_API_TOKEN, etc.). User should save the API token securely.
API flow (for CLI/agents):
Step 1 - Send OTP:
curl -X POST https://frames.ag/api/connect/start \
-H "Content-Type: application/json" \
-d '{"email":"your@email.com"}'Returns username in response. For referrals, add "ref":"REFERRER_USERNAME" to body.
Step 2 - Ask user for OTP, then complete:
curl -X POST https://frames.ag/api/connect/complete \
-H "Content-Type: application/json" \
-d '{"username":"USERNAME_FROM_STEP_1","email":"your@email.com","otp":"USER_OTP"}'Returns apiToken, evmAddress, solanaAddress. Save the apiToken for all wallet operations.
Share your referral link: https://frames.ag/connect?ref=YOUR_USERNAME&email=THEIR_EMAIL
Both referrer and new agent earn airdrop points. Points: referral (200), first tx (50), daily active (10), weekly streak (100).
Tiers: Bronze (0-4, 1x), Silver (5-24, 1.5x), Gold (25-99, 2x), Diamond (100+, 3x).
Check rewards:
curl https://frames.ag/api/wallets/YOUR_USERNAME/referrals \
-H "Authorization: Bearer FUND_API_TOKEN"Public network stats: GET https://frames.ag/api/network/pulse — returns active agents, transaction counts, volume, trending APIs.
Personal stats (authenticated): GET https://frames.ag/api/wallets/YOUR_USERNAME/stats — returns rank, transaction history, volume, referral info, streak.
| File | URL |
|------|-----|
| SKILL.md (this file) | https://frames.ag/skill.md |
| HEARTBEAT.md | https://frames.ag/heartbeat.md |
| package.json (metadata) | https://frames.ag/skill.json |
Run periodically to check for skill updates, wallet status, and recent activity:
curl https://frames.ag/heartbeat.mdBase URL: https://frames.ag/api/v1
Use your Fund API token (starts with mf_) as: Authorization: Bearer FUND_API_TOKEN
Check connection (public, no auth): GET https://frames.ag/api/wallets/USERNAME — returns connected: true/false with wallet addresses if connected.
Direct users to https://frames.ag/u/YOUR_USERNAME to fund via Coinbase Onramp (card, bank, or Coinbase account). Supports Base (USDC) and Solana (SOL).
Check balance after funding:
curl https://frames.ag/api/wallets/USERNAME/balances \
-H "Authorization: Bearer FUND_API_TOKEN"Balances: GET /api/wallets/USERNAME/balances (auth required)
Activity: GET /api/wallets/USERNAME/activity?limit=50 (auth optional — authenticated sees all events, public sees limited). Event types: otp., policy., wallet.action.*, x402.authorization.signed.
curl -X POST "https://frames.ag/api/wallets/USERNAME/actions/transfer" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"to":"0x...","amount":"1000000","asset":"usdc","chainId":8453}'Fields: to (address), amount (smallest units — ETH: 18 decimals, USDC: 6 decimals), asset ("eth" or "usdc"), chainId, idempotencyKey (optional).
Supported USDC chains: Ethereum (1), Sepolia (11155111), Optimism (10), Polygon (137), Arbitrum (42161), Base (8453), Base Sepolia (84532).
curl -X POST "https://frames.ag/api/wallets/USERNAME/actions/transfer-solana" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"to":"RECIPIENT","amount":"1000000000","asset":"sol","network":"devnet"}'Fields: to (address), amount (smallest units — SOL: 9 decimals, USDC: 6 decimals), asset ("sol" or "usdc"), network ("mainnet" or "devnet"), idempotencyKey (optional).
curl -X POST "https://frames.ag/api/wallets/USERNAME/actions/contract-call" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"to":"0x...","data":"0x...","value":"0","chainId":8453}'curl -X POST "https://frames.ag/api/wallets/USERNAME/actions/sign-message" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"chain":"solana","message":"hello"}'Request free devnet SOL for testing. Sends 0.1 SOL to your Solana wallet on devnet. Rate limited to 3 requests per 24 hours.
curl -X POST "https://frames.ag/api/wallets/USERNAME/actions/faucet-sol" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{}'Response: {"actionId":"...","status":"confirmed","amount":"0.1 SOL","txHash":"...","explorer":"...","remaining":2}
Response format for all actions: {"actionId":"...","status":"confirmed","txHash":"...","explorer":"..."}
Use this only if you need fine-grained control. For most cases, use x402/fetch above.
| Version | Payment Header | Network Format |
|---------|---------------|----------------|
| v1 | X-PAYMENT | Short names (solana, base) |
| v2 | PAYMENT-SIGNATURE | CAIP-2 (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) |
payment-required HEADER (body may be empty {}).POST /api/wallets/USERNAME/actions/x402/pay with {"requirement": "", "preferredChain": "evm"} . The requirement field accepts both base64 strings and JSON objects.usage.header response field and paymentSignature value.Signing endpoint: /api/wallets/{USERNAME}/actions/x402/pay (x402/pay with SLASH, not dash)
| Field | Type | Description |
|-------|------|-------------|
| requirement | string or object | Payment requirement (base64 or JSON) |
| preferredChain | "evm" or "solana" | Preferred blockchain |
| preferredChainId | number | Specific EVM chain ID |
| idempotencyKey | string | For deduplication |
| dryRun | boolean | Sign without storing (for testing) |
\ causes escaping errorsrequirement field (not deprecated paymentRequiredHeader)| Network | CAIP-2 Identifier | Token |
|---------|-------------------|-------|
| Base Mainnet | eip155:8453 | USDC |
| Base Sepolia | eip155:84532 | USDC |
| Solana Mainnet | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp | USDC |
| Solana Devnet | solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | USDC |
| Error | Solution |
|-------|----------|
| 404/405 on signing | Use /api/wallets/{USERNAME}/actions/x402/pay (slash not dash) |
| blank argument | Use single-line curl, not multiline with \ |
| AlreadyProcessed | Get a NEW signature for each request |
| insufficient_funds | Fund wallet at https://frames.ag/u/USERNAME |
Get current policy:
curl https://frames.ag/api/wallets/YOUR_USERNAME/policy \
-H "Authorization: Bearer FUND_API_TOKEN"Update policy:
curl -X PATCH https://frames.ag/api/wallets/YOUR_USERNAME/policy \
-H "Authorization: Bearer FUND_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"max_per_tx_usd":"25","allow_chains":["base","solana"],"allow_contracts":["0x..."]}'Success:
{"success": true, "data": {...}}Error:
{"success": false, "error": "Description", "hint": "How to fix"}AI Usage Analysis
Analysis is being generated… refresh in a few seconds.
Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau...
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
Search and analyze your own session logs (older/parent conversations) using jq.
Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linking related objects, enforcing constraints, planning multi-step actions as graph transformations, or when skills need to share state. Trigger on "remember", "what do I know about", "link X to Y", "show dependencies", entity CRUD, or cross-skill data access.
Ultimate AI agent memory system for Cursor, Claude, ChatGPT & Copilot. WAL protocol + vector search + git-notes + cloud backup. Never lose context again. Vibe-coding ready.
Headless browser automation CLI optimized for AI agents with accessibility tree snapshots and ref-based element selection