My Agent buys services#

Buyers don't need any complex setup — just install the Onchain OS Skill on your AI Agent, and it can initiate dialogue with Sellers and sign payments autonomously, with no human intervention throughout.

The Skill automatically handles:

• Payment request detection: Auto-detects HTTP 402 responses or payment URLs in messaging channels
• Amount verification: Checks whether the amount is reasonable and the recipient is trustworthy
• Signing authorization: Invokes Agentic Wallet to sign (one-time payment signs per call; Batch payment uses a pre-authorized Session Key)
• Status tracking: Monitors payment status and retrieves the Receipt

Prerequisites#

This guide runs through the full flow on X Layer Testnet, with no real funds required. Once verified, see the Switch to mainnet section at the end to go live.

• AI Agent: An AI tool that supports Skills, e.g. Claude Desktop
• Agentic Wallet: Created via Onchain OS Skill (email login, no seed phrase required); the private key is generated and kept inside a TEE. See Agentic Wallet installation for setup steps
• Testnet balance: On X Layer Testnet you'll need:
  • Gas (test OKB) → claim from the X Layer Faucet
  • Stablecoin (test USD₮0) → claim from the X Layer Faucet

Setup#

Send the following prompt to your AI to install Onchain OS Skills and configure Agentic Wallet for your Agent:

Run npx skills add okx/onchainos-skills to install Onchain OS skills
Note: please install into the skill directory of the current Agent
Also, help me install the latest CLI based on this document: https://github.com/okx/onchainos-skills

Verification#

The following uses the official Mock Merchant as the verification target — it's already deployed on X Layer Testnet, with no local service required.

Login:

onchainos wallet login

Request the Mock Merchant resource:

Access this service: https://www.okx.com/api/v1/pay/mock-merchant/resource

Receiving the payment info means the request succeeded:

The service returned an x402 payment-required response (HTTP 402). Contents:

  - x402 version: 2
  - Resource: /api/v1/pay/mock-merchant/resource
  - Payment method: exact — one-time payment
  - Network: eip155:1952 (X Layer Testnet)
  - Token: USD₮0 (0x9e29b3aada05bf2d2c827af80bd28dc0b9b4fb0c)
  - Amount: 10000 (smallest unit, i.e. 0.01 USD₮0)
  - Recipient: 0x3509655ad99effc7f3f74205482b1cb337ca08f7
  - Timeout: 60 seconds

Confirm the payment, sign the transaction data, and replay the request to the Seller:

PAYMENT_PAYLOAD=$(python3 -c "
      import json, base64
      payload = {
          'x402Version': 2,
          'resource': {'url': '/api/v1/pay/mock-merchant/resource', 'mimeType': 'application/json'},
          'accepted': {'scheme': 'exact', 'network': 'eip155:1952', 'asset':
      '0x9e29b3aada05bf2d2c827af80bd28dc0b9b4fb0c', 'amount': '10000', 'payTo':
      '0x3509655ad99effc7f3f74205482b1cb337ca08f7', 'maxTimeoutSeconds': 60, 'extra': {'name': 'USD₮0', 'version': '1'}},
          'payload': {
              'signature': '0x...',
              'authorization': {'from': '0x...', 'nonce':
              '0x...', 'to': '0x3509655ad99effc7f3f74205482b1cb337ca08f7', 'validAfter': '0', 'validBefore': '...', 'value': '10000'}
          }
      }
      print(base64.b64encode(json.dumps(payload, separators=(',', ':')).encode()).decode())
      ")
curl -s -D - https://www.okx.com/api/v1/pay/mock-merchant/resource -H "PAYMENT-SIGNATURE: $PAYMENT_PAYLOAD"

You receive the resource returned by the Seller:

⏺ Payment successful! Response returned:

  {
    "data": "premium content from mock merchant",
    "payment": {
      "status": "success",
      "payer": "0x...",
      "txHash": "0x...",
      "network": "eip155:1952"
    }
  }

Verify on-chain: copy the returned txHash into OKLink X Layer Testnet to confirm the transaction landed on-chain.

Switch to mainnet#

Once you've verified on testnet, going live only requires pointing your requests at a mainnet paid service and making sure your wallet holds real OKB (gas) + stablecoin (USDG / USD₮0).

No network config changes are needed on the buyer side: the network (eip155:196) and token address are returned by the Seller in the 402 response, and the Agent follows automatically.

FAQ#

Is it safe for the Agent to sign automatically?

Safe. The Agentic Wallet's private key is held inside a TEE (Trusted Execution Environment) and cannot be exported; the Skill validates amount and recipient before invoking the signature (see above); every signature includes nonce and validity window, so it cannot be replayed. For batch payment, a Session Key signature alone cannot go on-chain — it must be re-signed inside the TEE and aggregated, so even if intercepted it cannot directly trigger a charge.

Which wallets are supported?

One-time payment supports any EIP-3009-compatible EVM wallet. Batch payment requires Agentic Wallet.

What if payment fails?

When payment fails (e.g., KYT check fails, insufficient balance), the Seller does not deliver the service and the Buyer is not charged. The specific error code is returned to the Agent, and the reason is visible in the logs.

Can I use it without Agentic Wallet?

Yes, but features will be limited. Any EIP-3009 wallet can complete one-time payment; batch payment requires Agentic Wallet.