# payment

> Make and receive payments. Use this skill when you need to request payment from the user, or when the user asks you to pay via a payment link. Pay, get paid, and confirm payment.

- Author: Michael Yuan
- Repository: second-state/payment-skill
- Version: 20260203035852
- Stars: 127
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/second-state/payment-skill
- Web: https://mule.run/skillshub/@@second-state/payment-skill~payment:20260203035852

---

---
name: payment
description: Make and receive payments. Use this skill when you need to request payment from the user, or when the user asks you to pay via a payment link. Pay, get paid, and confirm payment.
---

# 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.

```bash
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.

```bash
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.

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

```bash
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.

```json
{"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.

```json
{"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.

```bash
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:**
```bash
scripts/get-address
```

**Output:** JSON with address and balance (if network is configured):
```json
{
  "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:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**

| Key | Description |
|-----|-------------|
| `wallet.path` | Path to wallet keystore file |
| `wallet.password_file` | Path to password file |
| `network.name` | Network name (e.g., "base-mainnet") |
| `network.chain_id` | Chain ID for transaction signing |
| `network.rpc_url` | Blockchain RPC endpoint URL |
| `payment.default_token` | Default ERC-20 token contract address |
| `payment.default_token_symbol` | Token symbol (e.g., "USDC") |
| `payment.default_token_decimals` | Token decimals (e.g., 6 for USDC) |
| `payment.max_auto_payment` | Maximum auto-payment amount |

---

## Configuration

Configuration file: `~/.payment/config.toml`

### Missing Config Behavior

When required config is missing, tools output JSON to stderr:
```json
{
  "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

| Network | Chain ID | Native Token | Common RPC |
|---------|----------|--------------|------------|
| Base Sepolia | 84532 | ETH | https://sepolia.base.org |
| Base Mainnet | 8453 | ETH | https://mainnet.base.org |
| Ethereum Sepolia | 11155111 | ETH | https://rpc.sepolia.org |
| Ethereum Mainnet | 1 | ETH | https://eth.llamarpc.com |

---

## 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:

```bash
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/`