AIOT Payment x402 is in public beta. Install the skill for your AI agent.
🤖 For AI Agentsx402-pay

x402-pay

Type: executable skill
Version: 0.1.0
Repo: aiot-network/aiot-x402-sdk

An executable skill that lets an AI agent autonomously pay for x402-gated HTTP endpoints. The skill handles the full protocol: detect the 402 response, sign the Permit2 authorization with the agent wallet, retry with the X-PAYMENT header, and return the paid response to the agent.

Install

$npx skills add aiot-network/aiot-x402-sdk/x402-pay
Executable skill that lets an AI agent pay for x402-gated HTTP endpoints autonomously. (v0.1.0)

Environment

The skill refuses to run without AIOT_AGENT_WALLET_KEY set:

export AIOT_AGENT_WALLET_KEY=0x<private-key>
Wallet key safety

Use a dedicated agent wallet funded with only as much USDC as the agent needs for the session. Never reuse a personal or treasury wallet. If the key leaks, the blast radius is limited to the agent balance.

Invoke

/x402-pay <url> [flags]

Example:

/x402-pay https://api.example.com/paywalled-endpoint

The skill will:

  1. GET the URL
  2. If the response is 402, parse the payment params from the body
  3. Check the amount against the max-amount cap (default 10 USDC)
  4. Sign the Permit2 authorization with the agent wallet
  5. Retry the request with X-PAYMENT: <encoded-signature> in the headers
  6. Return the paid response body + the on-chain transaction hash to the agent

Flags

NameTypeDescription
--max-amountnumberCap the payment at this many USDC. The skill refuses any payment above the cap.Default: 10
--dry-runbooleanWalk through the flow without actually signing or paying. Useful for debugging.Default: false
--chain-idnumberBSC chain id. 56 = mainnet, 97 = testnet.Default: 56
--facilitatorstringOverride the facilitator base URL.Default: https://merchant.aiotnetwork.io/api/v1
--timeoutnumberPer-request timeout in milliseconds.Default: 30000

Example: Claude Agent SDK

import Anthropic from '@anthropic-ai/sdk'
import { execSync } from 'node:child_process'
 
const client = new Anthropic()
 
const response = await client.messages.create({
  model: 'claude-opus-4-6',
  max_tokens: 1024,
  messages: [
    {
      role: 'user',
      content:
        'Fetch https://api.example.com/paywalled-endpoint. It costs USDC — ' +
        'pay it using /x402-pay and summarize the response.'
    }
  ]
})
 
// The agent invokes /x402-pay internally; stdout of the skill flows into
// the next tool-use step automatically. You don't need to shell out manually
// except for testing.

Safety model

The skill enforces three guardrails before any signature is produced:

  1. Max-amount cap — payments above --max-amount are rejected.
  2. Wallet balance check — the skill reads the wallet balance before signing and refuses if the balance is below the requested amount.
  3. Facilitator host allowlist — by default, the skill only trusts the AIOT facilitator. Override with --facilitator if you’ve deployed your own.

All three checks happen before any private-key operation, so a malicious URL can’t exfiltrate a signature.

Troubleshooting

“AIOT_AGENT_WALLET_KEY not set” — export the env var and re-run.

“Payment exceeds max amount” — bump --max-amount, or let the agent fail gracefully and report back to the operator.

“Wallet balance insufficient” — top up the agent wallet with USDC on the target chain.

“Facilitator returned 502” — the facilitator is having a bad day. Retry with backoff; the skill is idempotent from the agent’s point of view (each retry creates a fresh session).

“Invalid signature” — usually means the agent wallet is on a different chain than --chain-id. Verify the wallet’s chain with a dry-run.

Related

Installing Skillsx402-merchant