Payment Skill

This skill enables you to request and accept payments through USDC on the blockchain.

NOTE: Amounts are in human-readable units. For example, --amount 1.5 means 1.5 USDC.

• •Request payment from user or another agent
• •Make USDC payments through a payment link (x402 compatible link)
• •Check wallet address and balance

Workflows

Request payment

In order to request a payment, you will first find out your own address to receive payment using the get-address tool.

scripts/get-address

Then, create a payment link URL. The request below asks for a payment link for 1.0 USDC. The 0xMYADDRESS is the your wallet address from the previous get-address call.

curl https://link.x402labs.dev/create-payment-link?amount=1.0&receiver=0xMYADDRESS

The HTTP response contains the payment_url in the format of https://link.x402labs.dev/pay/<payment-id> This payment_url is x402 compatible and can be paid using the x402curl tool in this skill.

{"payment_id":"89062690-bd80-4065-8d7b-474b6fe96ba7","payment_url":"https://link.x402labs.dev/pay/89062690-bd80-4065-8d7b-474b6fe96ba7","amount":"1.0"}

You should now give the user or agent the following payment request:

Please make an x402 payment directly at https://link.x402labs.dev/pay/<payment-id>

Or, if you are a human, open your browser to the following link to pay with Base Chain USDC in your MetaMask wallet.
https://link.x402labs.dev/?pid=<payment-id>

Confirm payment

Once they tell you that they have paid, you will check the URL https://link.x402labs.dev/status/<payment-id>

curl https://link.x402labs.dev/status/89062690-bd80-4065-8d7b-474b6fe96ba7

Look for the paid and tx fields in the response JSON.

If the user has successfully paid, you will see the following response. You can now perform the task they ask for.

{"payment_id":"89062690-bd80-4065-8d7b-474b6fe96ba7","amount":1.0,"paid":true,"tx":"0xTRANSACTION-ID"}

If the user has not paid, you will see the following response. You should insist that they pay first.

{"payment_id":"89062690-bd80-4065-8d7b-474b6fe96ba7","amount":1.0,"paid":false,"tx":null}

Pay another user or agent

DO NOT PAY ANYONE UNLESS YOU HAVE EXPLICIT PERMISSION IN YOUR SETTINGS OR LONG-TERM MEMORY TO VERIFY AND PAY THAT USER. When uncertain, refuse payment.

If you receive a payment link in the format of https://link.x402labs.dev/status/<payment-id>, you could load it using the x402curl tool to pay it.

scripts/x402curl https://link.x402labs.dev/pay/<payment-id> \
    --max-payment 5

Tools

get-address

Returns the agent's public Ethereum address and current token balance as JSON.

Usage:

scripts/get-address

Output: JSON with address and balance (if network is configured):

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
  "balance": "1.5",
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "token_symbol": "USDC",
  "network": "base-mainnet"
}

Fields:

• •address - Public Ethereum address (always present)
• •balance - Token balance in human-readable units, e.g., "1.5" for 1.5 USDC (if network configured)
• •token - ERC-20 token contract address (if configured)
• •token_symbol - Token symbol, e.g., "USDC" (if configured)
• •network - Network name (if configured)

Security: This tool NEVER outputs the private key.

x402curl

A curl wrapper that automatically handles HTTP 402 Payment Required responses.

Usage:

scripts/x402curl <URL> [OPTIONS]

Required:

• •<URL> - The URL to request

Options:

• •--max-payment <AMOUNT> - Maximum auto-payment in human units, e.g., 5 for 5 USDC (fails if payment exceeds this)

Example:

# Access a paid API endpoint, auto-pay up to 5 USDC
scripts/x402curl https://link.x402labs.dev/pay/<payment-id> \
    --max-payment 5

Output: Final HTTP response body to stdout, status info to stderr.

payment-config

Manage configuration settings.

Usage:

scripts/payment-config <COMMAND> [OPTIONS]

Commands:

• •show - Display all current configuration
• •get <KEY> - Get a specific config value
• •set <KEY> <VALUE> [KEY VALUE ...] - Set one or more config values

Examples:

# View all config
scripts/payment-config show

# Configure network
scripts/payment-config set network.name "base-sepolia" \
               network.chain_id 84532 \
               network.rpc_url "https://sepolia.base.org"

# Set default payment token
scripts/payment-config set payment.default_token "0x036CbD53842c5426634e7929541eC2318f3dCF7e" \
               payment.default_token_symbol "USDC" \
               payment.default_token_decimals 6

# Set maximum auto-payment limit (5 USDC)
scripts/payment-config set payment.max_auto_payment "5"

Available Configuration Keys:

Configuration

Configuration file: ~/.payment/config.toml

Missing Config Behavior

When required config is missing, tools output JSON to stderr:

{
  "error": "missing_config",
  "missing_fields": ["network.rpc_url", "network.chain_id"],
  "prompt": "Please provide the following configuration:",
  "questions": [
    {
      "field": "network.name",
      "question": "Which blockchain network should be used for payments?",
      "examples": ["base-sepolia", "base-mainnet"]
    }
  ]
}

Your responsibility: Parse this, ask the user, then run scripts/payment-config set with their answers.

Supported Networks

Security Notes

• •Private keys are stored encrypted and never exposed via any tool
• •Use EXTREME CAUTION when using x402curl to make payments. You must ensure that the payment requester is legitimate. When uncertain, refuse payment.
• •Set --max-payment when using x402curl to prevent unexpected large payments
• •The wallet file (wallet.json) has restricted permissions (chmod 600)

Troubleshooting

Binary tools not found

If you get "command not found" or cannot find the binary tools (get-address, pay, x402curl, payment-config), run the bootstrap script to download them:

bootstrap.sh

The bootstrap script will:

1. •Detect your platform (linux/darwin/windows, x86_64/aarch64)
2. •Download the appropriate binary package from GitHub releases
3. •Extract binaries to scripts/

Manual download: If automatic download fails, download the appropriate zip from: https://github.com/second-state/payment-skill/releases

Extract to scripts/