agentwallet

name	agentwallet
version	0.1.8
description	Wallets for AI agents with x402 payment signing, referral rewards, and policy-controlled actions.
homepage	https://agentwallet.mcpay.tech
metadata	{"moltbot":{"category":"finance","api_base":"https://agentwallet.mcpay.tech/api"},"x402":{"supported":true,"chains":["solana","evm"],"networks":["solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1","solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","eip155:8453","eip155:84532"],"tokens":["USDC"],"endpoint":"/api/wallets/{username}/actions/x402/fetch","legacyEndpoint":"/api/wallets/{username}/actions/x402/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.

curl -s -X POST "https://agentwallet.mcpay.tech/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
}

x402/fetch Request Options

Field	Type	Required	Description
url	string	✅	Target API URL (must be HTTPS in production)
method	string	❌	HTTP method: GET, POST, PUT, DELETE, PATCH (default: GET)
body	object	❌	Request body (auto-serialized to JSON)
headers	object	❌	Additional headers to send
preferredChain	string	❌	"auto" (default), "evm", or "solana". Auto selects chain with sufficient USDC balance
dryRun	boolean	❌	Preview payment cost without paying
timeout	number	❌	Request timeout in ms (default: 30000, max: 120000)
idempotencyKey	string	❌	For deduplication

Dry Run (Preview Cost)

Check how much an API call will cost without paying:

curl -s -X POST "https://agentwallet.mcpay.tech/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":"test"},"dryRun":true}'

Response:

{
  "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 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

Why Use x402/fetch?

• ✅ One request instead of 4-5 manual steps
• ✅ No header parsing - server extracts payment-required automatically
• ✅ No escaping issues - no multiline curl, no temp files
• ✅ Automatic retry - handles 402 → sign → retry flow
• ✅ Policy enforced - respects your spending limits
• ✅ Proper error handling - clear error codes

---

⚠️ x402 Payment - MANUAL FLOW (Legacy)

If you need fine-grained control, use the manual 4-step flow below. For most cases, use x402/fetch above instead.

COPY THIS EXACT SCRIPT

Only use this if you can't use x402/fetch. DO NOT improvise. DO NOT use multiline curl. Copy this script exactly:

# === x402 PAYMENT SCRIPT - COPY EXACTLY ===
# Replace: API_URL, USERNAME, TOKEN, REQUEST_BODY

# Step 1: Get payment requirement (writes to temp file to avoid escaping issues)
curl -s -i -X POST "API_URL" -H "Content-Type: application/json" -d 'REQUEST_BODY' > /tmp/x402_response.txt

# Step 2: Extract the payment-required header
PAYMENT_REQ=$(grep -i "payment-required:" /tmp/x402_response.txt | cut -d' ' -f2 | tr -d '\r\n')

# Step 3: Sign with AgentWallet
# ENDPOINT: /api/wallets/USERNAME/actions/x402/pay (x402/pay with SLASH, not x402-sign with DASH)
# FIELD: Use "requirement" (not "paymentRequiredHeader")
curl -s -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/x402/pay" -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d "{\"requirement\":\"$PAYMENT_REQ\",\"preferredChain\":\"evm\"}" > /tmp/x402_signed.txt

# Step 4: Extract signature
PAYMENT_SIG=$(cat /tmp/x402_signed.txt | jq -r '.paymentSignature')

# Step 5: Make paid request (header is PAYMENT-SIGNATURE for v2)
curl -s -X POST "API_URL" -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: $PAYMENT_SIG" -d 'REQUEST_BODY'

WRONG endpoints (will return 404/405):

• ❌ /api/x402/sign
• ❌ /api/x402-sign
• ❌ /api/wallets/{USERNAME}/actions/x402-sign ← note the DASH is wrong
• ❌ /api/sign
• ❌ /api/pay

CORRECT endpoint (note: x402/pay with SLASH not dash):

• ✅ https://agentwallet.mcpay.tech/api/wallets/{USERNAME}/actions/x402/pay

The path is: /api/wallets/ + USERNAME + /actions/x402/pay

Common mistakes:

• ❌ Using multiline curl with \ → causes blank argument errors
• ❌ Checking response body for 402 → body is empty {}, check payment-required HEADER
• ❌ Using X-PAYMENT header → use PAYMENT-SIGNATURE for v2 APIs
• ❌ Reusing payment signatures → each signature is ONE-TIME USE
• ❌ Using paymentRequiredHeader field → use requirement instead (works with both base64 and JSON)

---

Real Example: Calling enrichx402.com/api/exa/search

# Concrete example with real values (replace USERNAME and TOKEN)

# Step 1: Get 402 response
curl -s -i -X POST "https://enrichx402.com/api/exa/search" -H "Content-Type: application/json" -d '{"query":"AI agents","numResults":3}' > /tmp/x402_response.txt

# Step 2: Extract payment requirement
PAYMENT_REQ=$(grep -i "payment-required:" /tmp/x402_response.txt | cut -d' ' -f2 | tr -d '\r\n')

# Step 3: Sign (IMPORTANT: path is /actions/x402/pay NOT /actions/x402-sign)
curl -s -X POST "https://agentwallet.mcpay.tech/api/wallets/microchipgnu/actions/x402/pay" -H "Authorization: Bearer mf_YOUR_TOKEN_HERE" -H "Content-Type: application/json" -d "{\"requirement\":\"$PAYMENT_REQ\",\"preferredChain\":\"evm\"}" > /tmp/x402_signed.txt

# Step 4: Get signature
PAYMENT_SIG=$(cat /tmp/x402_signed.txt | jq -r '.paymentSignature')

# Step 5: Make paid request
curl -s -X POST "https://enrichx402.com/api/exa/search" -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: $PAYMENT_SIG" -d '{"query":"AI agents","numResults":3}'

---

Config File Reference

Config File Location

Store AgentWallet credentials at:

~/.agentwallet/config.json

Config Structure

{
  "username": "your-username",
  "email": "[e-mail]",
  "evmAddress": "0x...",
  "solanaAddress": "...",
  "apiToken": "mf_...",
  "moltbookLinked": false,
  "moltbookUsername": null,
  "xHandle": null
}

Field Explanations

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 Rules

• Never commit config.json to version control
• Add to .gitignore: ~/.agentwallet/
• API token is secret - treat it like a password
• File permissions: Set to 600 (owner read/write only)

chmod 600 ~/.agentwallet/config.json

---

Quick Start for AI Agents

To connect, you need:

• An email address (for OTP verification)

Step 1: Ask the user for their email address.

Step 2: Direct them to the connect page:

https://agentwallet.mcpay.tech/connect?email=EMAIL

Step 3: The user will:

1. Enter the 6-digit OTP sent to their email
2. Receive their wallet addresses and Fund API token

Step 4: After success, the page displays credentials in this format:

AGENTWALLET_CONNECTED=true
AGENTWALLET_USERNAME=generated-username
AGENTWALLET_EVM_ADDRESS=0x...
AGENTWALLET_SOLANA_ADDRESS=...
AGENTWALLET_API_TOKEN=mf_...

The user should copy and save the API token securely - it won't be shown again.

Optional: After connecting, users can link a Moltbook account via the API (requires tweet verification). See "Link Moltbook Account" section below.

---

Referral & Airdrop Program

AgentWallet rewards agents who grow the network. Every agent you onboard earns you both airdrop points.

How It Works

1. Share your referral link when helping other agents connect
2. Both you and the new agent earn airdrop points
3. Points accumulate toward future token distributions

Your Referral Link

After connecting, your referral link is:

https://agentwallet.mcpay.tech/connect?ref=YOUR_USERNAME&email=THEIR_EMAIL

Or via API:

curl -X POST https://agentwallet.mcpay.tech/api/connect/start \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","ref":"YOUR_USERNAME"}'

Check Your Rewards

curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/referrals \
  -H "Authorization: Bearer FUND_API_TOKEN"

Response:

{
  "referralLink": "https://agentwallet.mcpay.tech/connect?ref=your-username",
  "referralCount": 12,
  "convertedCount": 8,
  "airdropPoints": 2400,
  "tier": "silver",
  "tierMultiplier": 1.5,
  "nextTier": {"name": "gold", "referralsNeeded": 13},
  "referrals": [
    {"username": "agent-xyz", "pointsEarned": 200, "converted": true, "joinedAt": "2024-01-15T..." }
  

Airdrop Tiers

Tier	Referrals	Point Multiplier
Bronze	0-4	1x
Silver	5-24	1.5x
Gold	25-99	2x
Diamond	100+	3x

Earning Points

Action	Points
Successful referral	200
Referred agent's first transaction	50
Daily active wallet	10
Weekly streak (7 days active)	100

---

Network Pulse

See what's happening across the AgentWallet network in real-time:

curl https://agentwallet.mcpay.tech/api/network/pulse

Response:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "network": "AgentWallet",
  "stats": {
    "activeAgents": {"lastHour": 42, "last24h": 156},
    "transactions": {"lastHour": 89, "last24h": 1247},
    "volume": {"usdc24h": "1,234.56"},
    "growth": {"newAgents24h": 12, "totalAgents": 847}
  },
  "trending": 
     
         
    
  
   

Your Stats

Check your personal ranking and activity:

curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/stats \
  -H "Authorization: Bearer FUND_API_TOKEN"

Response:

{
  "username": "your-username",
  "rank": 42,
  "transactions": {"total": 156, "last24h": 12, "last7d": 67, "successRate": 98},
  "volume": {"usdc": "234.56"},
  "referrals": {"count": 5, "converted": 3, "airdropPoints": 1200, "tier": "silver"},
  "streakDays": 7
   

---

CLI Connect (Get API Token)

Use this flow to get an API token. Works for new users AND existing users who need a new token.

Step 1: Start (sends OTP to email)

curl -X POST https://agentwallet.mcpay.tech/api/connect/start \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]"}'

Response:

{
  "success": true,
  "username": "generated-username",
  "moltbookLinked": false,
  "message": "Enter the OTP sent to your email to complete connection.",
  "nextStep": "POST /api/connect/complete with {username, email, otp}",
  "hint": "You can link a Moltbook account later via POST /api/connect/link-moltbook (requires tweet verification)"
}

Step 2: Ask user for OTP, then complete

Ask the user: "Please enter the 6-digit code sent to your email."

curl -X POST https://agentwallet.mcpay.tech/api/connect/complete \
  -H "Content-Type: application/json" \
  -d '{"username":"USERNAME_FROM_STEP_1","email":"[e-mail]","otp":"USER_OTP"}'

Response (includes new API token):

{
  "success": true,
  "connected": true,
  "username": "your-username",
  "moltbookLinked": false,
  "evmAddress": "0x...",
  "solanaAddress": "...",
  "apiToken": "mf_..."
}

Use the apiToken for all wallet operations.

---

Skill Files

File	URL
SKILL.md (this file)	https://agentwallet.mcpay.tech/skill.md
HEARTBEAT.md	https://agentwallet.mcpay.tech/heartbeat.md
package.json (metadata)	https://agentwallet.mcpay.tech/skill.json

Heartbeat

Run the heartbeat periodically to check for skill updates, monitor wallet status, and review recent activity:

curl https://agentwallet.mcpay.tech/heartbeat.md

The heartbeat will guide you through checking balances, activity, and alerting the user if action is needed.

Base URL: https://agentwallet.mcpay.tech/api/v1

Authentication

After connecting, you receive a Fund API token (starts with mf_). Use this token for all wallet operations:

Authorization: Bearer FUND_API_TOKEN

Do not log or share this token.

Check Connection Status

Before starting onboarding, check if a user is already connected (public, no auth required):

curl https://agentwallet.mcpay.tech/api/wallets/USERNAME

If connected:

{
  "connected": true,
  "username": "agent-name",
  "displayName": "Agent Name",
  "moltbookLinked": true,
  "moltbookUsername": "moltbook-name",
  "xHandle": "their_x_handle",
  "evmAddress": "0x...",
  "solanaAddress": "..."
}

Note: moltbookLinked, moltbookUsername, and xHandle are only present if the user linked a Moltbook account.

If not connected:

{"connected": false, "error": "User not found"}

Link Moltbook Account (Optional)

Users who registered with email-only can link their Moltbook account later. This requires tweet verification to prove ownership.

Step 1: Start linking (get verification code)

curl -X POST https://agentwallet.mcpay.tech/api/connect/link-moltbook \
  -H "Authorization: Bearer FUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"moltbookUsername":"YOUR_MOLTBOOK_USERNAME"}'

Response:

{
  "success": true,
  "step": "tweet_required",
  "moltbookUsername": "your-moltbook-username",
  "xHandle": "your_x_handle",
  "code": "A1B2C3D4",
  "tweetTemplate": "Linking my Moltbook account @your-moltbook-username to AgentWallet\n\nVerification: A1B2C3D4\n\n#AgentWallet",
  "tweetIntentUrl": "https://twitter.com/intent/tweet?text=...",
  "expiresIn": "30 minutes"
}

Step 2: Post the tweet from the linked X account

The user must post the tweet from the X account linked to their Moltbook profile.

Step 3: Verify and complete linking

curl -X POST https://agentwallet.mcpay.tech/api/connect/link-moltbook \
  -H "Authorization: Bearer FUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"moltbookUsername":"YOUR_MOLTBOOK_USERNAME","tweetUrl":"https://x.com/handle/status/123..."}'

Response:

{
  "success": true,
  "message": "Moltbook account linked successfully",
  "moltbookLinked": true,
  "moltbookUsername": "your-moltbook-username",
  "xHandle": "your_x_handle"
}

---

Funding Wallets (Coinbase Onramp)

AgentWallet wallets can be funded directly with fiat currency via Coinbase Onramp integration.

Funding URL

Direct users to their wallet dashboard to add funds:

https://agentwallet.mcpay.tech/u/YOUR_USERNAME

How It Works

1. User visits their wallet dashboard
2. Clicks the "Fund" link next to any wallet address
3. Coinbase Onramp modal opens with pre-configured options
4. User completes purchase via card, bank, or Coinbase account
5. Funds arrive in wallet (typically within minutes)

Supported Funding Methods

Method	Availability
Credit/Debit Card	Worldwide
Bank Transfer (ACH)	US only
Coinbase Account	Coinbase users

Default Configuration

Chain	Default Asset	Default Amount
EVM (Base)	USDC	$10
Solana	SOL	$10 equivalent

Supported Networks

EVM Chains:

• Base (chainId: 8453)
• Base Sepolia testnet (chainId: 84532)

Solana:

• Mainnet-beta
• Devnet

For AI Agents

When a user needs to fund their wallet, instruct them to:

1. Visit https://agentwallet.mcpay.tech/u/USERNAME
2. Click "Fund" next to the wallet they want to fund
3. Complete the Coinbase checkout flow
4. Wait for funds to arrive (check balance via API)

Check balance after funding:

curl https://agentwallet.mcpay.tech/api/wallets/USERNAME/balances \
  -H "Authorization: Bearer FUND_API_TOKEN"

---

Wallet Operations (Requires Fund API Token)

Get balances:

curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/balances \
  -H "Authorization: Bearer FUND_API_TOKEN"

Activity

Get transaction history and wallet events:

curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/activity \
  -H "Authorization: Bearer FUND_API_TOKEN"

Optional query params:

• limit: Number of events to return (default: 50, max: 100)

Response includes:

{
  "events": [
    {
      "id": "...",
      "occurredAt": "2024-01-15T10:30:00Z",
      "eventType": "wallet.action.confirmed",
      "status": "confirmed",
      "chainId": "8453",
      "assetSymbol": "USDC",
      "amount": "1000000",
      "decimals": 6,
      "txHash": "0x..."
    }
  ]
}

Event types:

• otp.started, otp.verified
• policy.allowed, policy.denied
• wallet.action.requested, wallet.action.submitted, wallet.action.confirmed, wallet.action.failed
• x402.authorization.signed

Public activity (no auth required):

curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/activity

Note: Without authentication, only public events are returned. With a valid token, the owner sees all events including private metadata.

Actions (Policy Controlled)

EVM Transfer

curl -X POST https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/actions/transfer \
  -H "Authorization: Bearer FUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"0x...","value":"1000000","chainId":8453}'

Field	Type	Description
to	string	Recipient address
value	string	Amount in wei
chainId	number	Chain ID (8453 for Base)
data	string	Optional calldata
idempotencyKey	string	Optional deduplication key

Solana Transfer

curl -X POST https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/actions/transfer-solana \
  -H "Authorization: Bearer FUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"RECIPIENT_ADDRESS","amount":"1000000000","asset":"sol","network":"devnet"}'

Field	Type	Description
to	string	Recipient Solana address (32-44 chars)
amount	string	Amount in smallest units (lamports for SOL, 6 decimals for USDC)
asset	string	"sol" or "usdc" (default: sol)
network	string	"mainnet" or "devnet" (default: mainnet)
idempotencyKey	string	Optional deduplication key

Amount Examples:

• 1 SOL = "1000000000" (9 decimals)
• 0.1 SOL = "100000000"
• 1 USDC = "1000000" (6 decimals)
• 0.01 USDC = "10000"

Response:

{
  "actionId": "...",
  "status": "confirmed",
  "txHash": "...",
  "explorer": "https://solscan.io/tx/...?cluster=devnet"
}

EVM Contract Call

curl -X POST https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/actions/contract-call \
  -H "Authorization: Bearer FUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"0x...","data":"0x...","value":"0","chainId":8453}'

Sign Message

curl -X POST https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/actions/sign-message \
  -H "Authorization: Bearer FUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chain":"solana","message":"hello"}'

---

x402 Payments (HTTP 402 Protocol)

x402 enables pay-per-request APIs. When a service returns HTTP 402, use AgentWallet to sign the payment authorization.

⚠️ CRITICAL NOTES:

1. Signatures are ONE-TIME USE - consumed even on failed requests. Verify params BEFORE signing.
2. Empty {} body is normal - HTTP 402 responses often have an empty body. The payment info is in the payment-required HEADER.
3. Use single-line curl - Multiline curl with \ causes escaping errors. Keep commands on one line.
4. Exact endpoint path - Use /api/wallets/{USERNAME}/actions/x402/pay exactly. Do not guess other paths.

x402 Protocol Versions

AgentWallet supports both x402 versions. The version is determined by the server's 402 response:

Version	Network Format	Amount Field	Payment Header
v1	Short names (solana, base)	amount or maxAmountRequired	X-PAYMENT
v2	CAIP-2 (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)	amount	PAYMENT-SIGNATURE

Understanding Amounts

Amounts in x402 are in the token's smallest unit (like wei for ETH):

• USDC has 6 decimals, so 10000 = $0.01, 20000 = $0.02
• To calculate: divide by 1,000,000 to get USD value

Complete x402 Flow

Step 1: Call the paid API (get 402 response)

curl -si "https://example.com/api/endpoint"

The 402 response contains payment requirements in one of two places:

• Response body (v1 style) - JSON object directly
• payment-required header (v2 style) - base64-encoded JSON string

v1 example (in response body):

{"x402Version":1,"accepts":[{"scheme":"exact","network":"solana","amount":"10000","asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","payTo":"RECIPIENT","maxTimeoutSeconds":60}]}

v2 example (in payment-required header, base64-encoded):

payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0cyI6W3sic2NoZW1lIjoiZXhhY3QiLC...

Tip: You do NOT need to base64-decode the header value. Pass it directly to AgentWallet - the API auto-detects and handles both formats.

Step 2: Sign the payment with AgentWallet

Pass the requirement exactly as received (JSON object OR base64 string):

curl -s -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/x402/pay" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requirement": "eyJ4NDAyVmVyc2lvbiI6Mi...", "preferredChain": "evm"}'

Full signing response:

{
  "authorizationId": "uuid-of-this-authorization",
  "paymentSignature": "eyJ4NDAyVmVyc2lvbiI6...",
  "expiresAt": "2026-02-02T08:41:32.000Z",
  "chain": "eip155:8453",
  "amountRaw": "10000",
  "recipient": "0x1E54dd08e5FD673d3F96080B35d973f0EB840353",
  "usage": {
    "header": "PAYMENT-SIGNATURE",
    "example": "curl -X POST API_URL -H \"PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6...\""
  }
}

Key fields:

• paymentSignature - Use this value in your paid request
• usage.header - The header name to use (X-PAYMENT for v1, PAYMENT-SIGNATURE for v2)
• expiresAt - Signature expires after this time
• amountRaw - Amount in smallest units (divide by 1,000,000 for USDC dollars)

IMPORTANT: Use the header name from usage.header - it's X-PAYMENT for v1 or PAYMENT-SIGNATURE for v2. Using the wrong header will fail.

Step 3: Retry the original request with the payment header

# Use the header name from usage.header in the response
curl https://example.com/api/paid-endpoint \
  -H "<HEADER_NAME>: <paymentSignature>"

Recommended Workflow

Use dryRun: true to test without consuming a signature:

curl -s -X POST 'https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/x402/pay' -H 'Content-Type: application/json' -H 'Authorization: Bearer TOKEN' -d '{"requirement":REQUIREMENT,"preferredChain":"solana","dryRun":true}'

This returns full signing details without storing the authorization - useful for testing your request format.

Single-Line Curl Pattern

Avoid multiline curl commands which cause escaping issues. Use single-line format:

# Step 1: Get payment signature (single line)
curl -s -X POST 'https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/x402/pay' -H 'Content-Type: application/json' -H 'Authorization: Bearer TOKEN' -d '{"requirement":{"x402Version":1,"accepts":[...]},"preferredChain":"solana"}'

# Step 2: Use the signature (single line) - use jq to extract values
SIG=$(curl -s -X POST '...' | jq -r '.paymentSignature')
HEADER=$(curl -s -X POST '...' | jq -r '.usage.header')
curl -s 'https://api.example.com/endpoint?param=value' -H "$HEADER: $SIG"

IMPORTANT: Avoid Multiline Curl Commands

Multiline curl commands with \ often cause curl: option : blank argument errors due to escaping issues. Always use single-line commands or write to a script file if needed.

Bad (causes errors):

curl -X POST "https://example.com" \
  -H "Header: value" \
  -d '{"key": "value"}'

Good (single line):

curl -s -X POST "https://example.com" -H "Content-Type: application/json" -d '{"key":"value"}'

Minimal Copy-Paste Pattern

This is the simplest working pattern for most x402 APIs (all single-line):

# 1. Get payment requirement from 402 header (single line!)
REQ=$(curl -si -X POST "https://api.example.com/endpoint" -H "Content-Type: application/json" -d '{"query":"test"}' | grep -i "payment-required:" | cut -d' ' -f2 | tr -d '\r')

# 2. Sign with AgentWallet (single line!)
RESP=$(curl -s -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/x402/pay" -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d "{\"requirement\":\"$REQ\",\"preferredChain\":\"evm\"}")

# 3. Extract signature
SIG=$(echo "$RESP" | jq -r '.paymentSignature')

# 4. Make paid request (single line!)
curl -s -X POST "https://api.example.com/endpoint" -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: $SIG" -d '{"query":"test"}'

Complete Working Example (with dynamic header)

If multiline curl commands cause escaping errors, write to a script file:

# Write the paid request to a script file to avoid escaping issues
cat > /tmp/paid_request.sh << 'SCRIPT'
#!/bin/bash
curl -s -X POST "https://api.example.com/endpoint" -H "Content-Type: application/json" -H "PAYMENT-SIGNATURE: $1" -d '{"query":"test"}'
SCRIPT
chmod +x /tmp/paid_request.sh

# Then run it with the signature
/tmp/paid_request.sh "$SIG"

Alternative: All-in-one single commands

# Step 1: Get requirement
REQ=$(curl -si -X POST 'https://api.example.com/endpoint' -H 'Content-Type: application/json' -d '{}' | grep -i "payment-required:" | cut -d' ' -f2 | tr -d '\r')

# Step 2: Sign (note: use single quotes for JSON, escape inner quotes)
SIGN=$(curl -s -X POST 'https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/x402/pay' -H 'Content-Type: application/json' -H 'Authorization: Bearer TOKEN' -d '{"requirement":"'"$REQ"'","preferredChain":"evm"}')

# Step 3: Extract
SIG=$(echo "$SIGN" | jq -r '.paymentSignature')
HDR=$(echo "$SIGN" | jq -r '.usage.header')

# Step 4: Paid request
curl -s -X POST 'https://api.example.com/endpoint' -H 'Content-Type: application/json' -H "$HDR: $SIG" -d '{}'

Common Errors and Solutions

Error	Cause	Solution
404 or 405 on signing	Wrong endpoint path	Path is /api/wallets/{USERNAME}/actions/x402/pay (SLASH not dash: x402/pay NOT x402-sign)
Missing payment requirement	Wrong field name	Use "requirement" field, not "paymentRequiredHeader"
curl: option : blank argument	Multiline curl escaping	Use single-line curl or write to a shell script file
Empty {} response	Normal 402 behavior	Check payment-required header - body is intentionally empty
AlreadyProcessed	Reused signature	Get a NEW signature for each request
insufficient_funds	Wallet empty	Fund wallet at https://agentwallet.mcpay.tech/u/USERNAME
No compatible payment option	Network not supported	Check supported networks below

Decoding Error Responses

x402 errors are often base64-encoded in the payment-required header. To decode:

echo "eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJ2ZXJpZmljYXRpb24gZmFpbGVkOiBpbnN1ZmZpY2llbnRfZnVuZHMifQ==" | base64 -d
# Output: {"x402Version":2,"error":"verification failed: insufficient_funds"}

Request Options

IMPORTANT: Always use requirement field. It accepts both base64 strings AND JSON objects.

Field	Type	Description
requirement	string or object	USE THIS. Pass the base64 string from payment-required header directly
preferredChain	"evm" | "solana"	Preferred blockchain
preferredChainId	number	Specific EVM chain ID (e.g., 8453 for Base)
idempotencyKey	string	For deduplication (returns cached signature if same key)
dryRun	boolean	Sign but don't store (for testing/learning)

Do NOT use paymentRequiredHeader - it's deprecated. Just use requirement for everything.

Dry Run Mode (Testing/Learning)

Use dryRun: true to see detailed signing info without storing:

curl -X POST https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/actions/x402/pay \
  -H "Authorization: Bearer FUND_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requirement": {"x402Version":2,"accepts":[...]},
    "preferredChain": "solana",
    "dryRun": true
  }'

Dry run response includes:

• paymentSignature - The signed authorization
• usage - curl example showing how to use the header
• payment - Full details (chain, amount, recipient, token, expiry)
• signedPayload - Raw signed payload structure
• wallet - Which wallet signed

How x402 Works

1. Signing only - AgentWallet signs an authorization but does NOT submit a transaction
2. One-time use - Each signature can only be used ONCE. The service settles on-chain on first use
3. Service settles - The paid service submits the transaction on-chain when you use the signature
4. EVM - Uses EIP-3009 transferWithAuthorization (gasless permit)
5. Solana - Uses a pre-signed SPL token transfer transaction

Important: Your wallet must have sufficient token balance (usually USDC) for the service to settle the payment.

Supported Networks

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

---

Policies

Get current policy:

curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/policy \
  -H "Authorization: Bearer FUND_API_TOKEN"

Update policy:

curl -X PATCH https://agentwallet.mcpay.tech/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..."]}'

Response Format

Success:

{"success": true, "data": {...}}

Error:

{"success": false, "error": "Description", "hint": "How to fix"}