x402

x402 — BSV Micropayment Client

Make authenticated and paid API requests to BSV AI services. Discover agents, authenticate with BRC-31, pay with BRC-29 micropayments — all from natural language.

Prerequisites

• •MetaNet Client running at localhost:3321 (download from getmetanet.com)
• •Python 3 with requests installed (pip3 install requests)

Available Services

Instructions

Resolve the helper script path first:

HELPER="$HOME/.agents/skills/x402/scripts/brc31_helpers.py"
if [ ! -f "$HELPER" ] && [ -n "${CODEX_HOME:-}" ]; then
  HELPER="$CODEX_HOME/skills/x402/scripts/brc31_helpers.py"
fi

If HELPER still does not exist, ask the user where x402 is installed and use that path.

Step 1: Determine what the user wants

Parse the user's request into one of these actions:

• •List agents — user wants to see what's available
• •Discover agent — user wants details/pricing for a specific agent
• •Auth request — user wants to call an endpoint that requires authentication but no payment
• •Paid request — user wants to generate an image, video, transcribe audio, search Twitter, upload a file, etc.

If the request is ambiguous, ask the user to clarify which agent or action they want.

Step 2: Run the appropriate command

List all agents

python3 "$HELPER" list

Discover an agent's capabilities and pricing

python3 "$HELPER" discover <agent-name>

Agent names: banana, veo, whisper, x-research, kling, 1sat, nanostore.

Get wallet identity

python3 "$HELPER" identity

Authenticated request (no payment)

python3 "$HELPER" auth <METHOD> <agent/path> [body-json]

Paid request (auth + automatic 402 payment)

python3 "$HELPER" pay <METHOD> <agent/path> [body-json]

This handles the full flow automatically:

1. •Sends initial request -> server returns 402 with price
2. •Creates payment transaction via MetaNet Client wallet
3. •Retries with payment header -> server accepts, returns result
4. •If response includes a refund, auto-processes it back to the wallet
5. •If response includes an action template (e.g. 1sat-agent), returns pending_action for explicit execution

Execute a pending wallet action (broadcast)

python3 "$HELPER" execute-action '<action-json>'

Use this after pay when the response includes pending_action.action.

Step 3: Construct the request

When the user gives a natural-language request like "generate an image of a sunset":

1. •Run list to find the matching agent (banana for images, veo for video, etc.)
2. •Run discover <agent> to read the endpoint schemas and required fields
3. •Build the JSON body from the schema and user's request
4. •Run pay POST <agent>/<endpoint> '<json-body>'

Agent name resolution: Short names like banana or nanostore resolve automatically via the x402agency.com registry. Full URLs (https://...) also work.

Examples:

# Generate an image
python3 "$HELPER" pay POST banana/generate '{"prompt":"a mountain sunset","aspect_ratio":"16:9"}'

# Search Twitter
python3 "$HELPER" pay POST x-research/search '{"query":"bitcoin scaling","max_results":20}'

# Transcribe audio (base64-encoded)
python3 "$HELPER" pay POST whisper/transcribe '{"audio":"<base64>","language":"en"}'

# Free authenticated endpoint
python3 "$HELPER" auth POST banana/free

# Inscribe a 1Sat Ordinal (requires explicit action execution)
PAY_JSON=$(python3 "$HELPER" pay POST 1sat/inscribe '{"data":"aGVsbG8=","contentType":"text/plain","publicKey":"02..."}')
python3 "$HELPER" execute-action "$(echo "$PAY_JSON" | jq -c '.pending_action.action')"

Step 4: Present the result

• •Parse the JSON response from the script
• •For images/video: extract the URL and show it to the user
• •For text results (transcription, search): format and display clearly
• •For errors: show the error message and suggest fixes
• •If a refund was processed, mention it to the user
• •If pending_action is present, execute it and return txid / inscription_id

Error handling

• •MetaNet Client not running: Tell the user to start MetaNet Client from /Applications or download from getmetanet.com
• •402 Payment Required with no auto-payment: The script handles this automatically; if it fails, show the payment details from the 402 headers
• •Agent not found: Run list to show available agents
• •Auth failure (401/403): Run python3 "${HELPER%/scripts/brc31_helpers.py}/cli.py" session --clear-all then retry
• •requests not installed: Run pip3 install requests

Protocol Summary

• •BRC-31: Mutual HTTP authentication with identity keys and signed requests
• •BRC-29: HTTP micropayments via 402 Payment Required flow
• •BRC-100: MetaNet Client wallet interface (key derivation, signing, tx creation)