I'm an Agent Buyer#

Buyers don't need a complex SDK — just install the Onchain OS Skill on your AI Agent. It can then negotiate with Sellers, declare the service it needs, and sign payments autonomously, with no human intervention.

The Skill handles the following on your Agent's behalf:

• Payment-request detection: auto-detects HTTP 402 responses and payment URLs in messaging channels
• Amount validation: checks whether the amount is reasonable and the recipient is trustworthy
• Signing authorization: invokes Agentic Wallet to sign (one signature per payment for One-time; uses pre-authorized Session Key for Batch)
• Status tracking: monitors payment status and fetches the settlement receipt

Prerequisites#

• AI Agent: an AI tool that supports Skills, e.g. Claude Desktop
• Agentic Wallet: created through Onchain OS Skill (email login, no seed phrase needed); the private key is generated and held inside a TEE. See Agentic Wallet installation
• On-chain balance: sufficient USDG / USD₮0 on X Layer

Configuration#

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

Run `npx skills add okx/onchainos-skills` to install Onchain OS skills.
Note: please install to the skill directory of the current Agent.
Also, install the latest version of the CLI per this doc: https://github.com/okx/onchainos-skills

Verify#

The "weather query" example below is illustrative — substitute with the actual paid x402 service you want to test.

Log in:

onchainos wallet login

Request the Seller's service / resource:

// Not a live service — illustrative only
Access this service: http://localhost:4021/weather

Receiving the payment info means the request worked:

The service returned an x402 Payment Required response (HTTP 402). Contents:

  - x402 version: 2
  - Resource: /weather — Get current weather data for any location, returns application/json
  - Payment options (two schemes):
    - exact — One-time payment
    - aggr_deferred — Post-pay (batch)
  - Network: eip155:196 (OKX X Layer)
  - Token: USD₮0 (0x779ded0c9e1022225f8e0630b35a9b54be713736)
  - Amount: 1000 (atomic units)
  - Recipient: 0xb483abdb92f8061e9a3a082a4aaaa6b88c381308
  - Timeout: 600,000 seconds

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

PAYMENT_PAYLOAD=$(python3 -c "
      import json, base64
      payload = {
          'x402Version': 2,
          'resource': {'url': '/weather', 'description': 'Get current weather data for any location', 'mimeType':
      'application/json'},
          'accepted': {'scheme': 'exact', 'network': 'eip155:196', 'asset':
      '0x779ded0...4be713736', 'amount': '1000', 'payTo':
      '0xb483abd....aa6b88c381308', 'maxTimeoutSeconds': 600000, 'extra': {'name': 'USD₮0',
      'version': '1'}},
          'payload': {
              'signature': '0x3d1907a6ba9f592c...35868ea11b',
              'authorization': {'from': '0xbda9fde...99763', 'nonce':
              '0x20862cc...06e48', 'to':
              '0xb483abd...81308', 'validAfter': '0', 'validBefore': '1775837508', 'value': '1000'}
          }
      }
      print(base64.b64encode(json.dumps(payload, separators=(',', ':')).encode()).decode())
      ")
curl -s -D - http://localhost:4021/weather -H "PAYMENT-SIGNATURE: $PAYMENT_PAYLOAD"

Get the resource back from the Seller:

⏺ Payment succeeded! Weather data returned:

  {"report": {"temperature": 70, "weather": "sunny"}}

  - Temperature: 70°F
  - Weather: sunny ☀️

FAQ#

Is Agent auto-signing safe?

Safe. The Agent can only auto-sign within the Session Key scope you pre-authorized (amount, validity, purpose are all bounded). Even if the Agent is compromised, the loss is limited to the authorized scope. For One-time payments, each transaction still requires confirmation from the main wallet.

Which wallets are supported?

One-time payment supports any EIP-3009-compatible EVM wallet. Batch payment (Session Key authorization) requires Agentic Wallet.

What if a payment fails?

When a payment fails (e.g. KYT screening blocks it, insufficient balance, Session Key expired), the Seller doesn't deliver the service and the Buyer isn't charged. The specific error code is returned to the Agent and you can see the reason in the logs.

Can I use it without Agentic Wallet?

Yes, with limitations. Any EIP-3009 wallet can complete One-time payments; using Batch payment's Session Key authorization requires Agentic Wallet.