Onchain OS x402 Payment

Sign an x402 payment authorization and return the payment proof for accessing payment-gated resources. Supports TEE signing (via wallet session) or local signing (with user's own private key).

Pre-flight Checks

Every time before running any onchainos command, always follow these steps in order. Do not echo routine command output to the user; only provide a brief status update when installing, updating, or handling a failure.

1. Resolve latest stable version: Fetch the latest stable release tag from the GitHub API:

   curl -sSL "https://api.github.com/repos/okx/onchainos-skills/releases/latest"
   

   Extract the tag_name field (e.g., v1.0.5) into LATEST_TAG. If the API call fails and onchainos is already installed locally, skip steps 2-3 and proceed to run the command (the user may be offline or rate-limited; a stale binary is better than blocking). If onchainos is not installed, stop and tell the user to check their network connection or install manually from https://github.com/okx/onchainos-skills.

2. Install or update: If onchainos is not found, or if the cache at ~/.onchainos/last_check ($env:USERPROFILE\.onchainos\last_check on Windows) is older than 12 hours:

   • Download the installer and its checksum file from the latest release tag:
     • macOS/Linux: curl -sSL "https://raw.githubusercontent.com/okx/onchainos-skills/${LATEST_TAG}/install.sh" -o /tmp/onchainos-install.sh curl -sSL "https://github.com/okx/onchainos-skills/releases/download/${LATEST_TAG}/installer-checksums.txt" -o /tmp/installer-checksums.txt
     • Windows: Invoke-WebRequest -Uri "https://raw.githubusercontent.com/okx/onchainos-skills/${LATEST_TAG}/install.ps1" -OutFile "$env:TEMP\onchainos-install.ps1" Invoke-WebRequest -Uri "https://github.com/okx/onchainos-skills/releases/download/${LATEST_TAG}/installer-checksums.txt" -OutFile "$env:TEMP\installer-checksums.txt"
   • Verify the installer's SHA256 against installer-checksums.txt. On mismatch, stop and warn — the installer may have been tampered with.
   • Execute: sh /tmp/onchainos-install.sh (or & "$env:TEMP\onchainos-install.ps1" on Windows). The installer handles version comparison internally and only downloads the binary if needed.
   • On other failures, point to https://github.com/okx/onchainos-skills.

3. Verify binary integrity (once per session): Run onchainos --version to get the installed version (e.g., 1.0.5 or 2.0.0-beta.0). Construct the installed tag as v<version>. Download checksums.txt for the installed version's tag (not necessarily LATEST_TAG): curl -sSL "https://github.com/okx/onchainos-skills/releases/download/v<version>/checksums.txt" -o /tmp/onchainos-checksums.txt Look up the platform target and compare the installed binary's SHA256 against the checksum. On mismatch, reinstall (step 2) and re-verify. If still mismatched, stop and warn.

   • Platform targets — macOS: arm64->aarch64-apple-darwin, x86_64->x86_64-apple-darwin; Linux: x86_64->x86_64-unknown-linux-gnu, aarch64->aarch64-unknown-linux-gnu, i686->i686-unknown-linux-gnu, armv7l->armv7-unknown-linux-gnueabihf; Windows: AMD64->x86_64-pc-windows-msvc, x86->i686-pc-windows-msvc, ARM64->aarch64-pc-windows-msvc
   • Hash command — macOS/Linux: shasum -a 256 ~/.local/bin/onchainos; Windows: (Get-FileHash "$env:USERPROFILE\.local\bin\onchainos.exe" -Algorithm SHA256).Hash.ToLower()

4. Check for skill version drift (once per session): If onchainos --version is newer than this skill's metadata.version, display a one-time notice that the skill may be outdated and suggest the user re-install skills via their platform's method. Do not block.

5. Do NOT auto-reinstall on command failures. Report errors and suggest onchainos --version or manual reinstallation from https://github.com/okx/onchainos-skills.

6. Rate limit errors. If a command hits rate limits, the shared API key may be throttled. Suggest creating a personal key at the OKX Developer Portal. If the user creates a .env file, remind them to add .env to .gitignore.

Skill Routing

• For querying authenticated wallet balance / send tokens / tx history → use okx-agentic-wallet
• For querying public wallet balance (by address) → use okx-wallet-portfolio
• For token swaps / trades / buy / sell → use okx-dex-swap
• For token search / metadata / rankings / holder info / cluster analysis → use okx-dex-token
• For token prices / K-line charts / wallet PnL / address tracker activities → use okx-dex-market
• For smart money / whale / KOL signals / leaderboard → use okx-dex-signal
• For meme / pump.fun token scanning → use okx-dex-trenches
• For transaction broadcasting / gas estimation → use okx-onchain-gateway
• For security scanning (token / DApp / tx / signature) → use okx-security

Chain Name Support

--network uses CAIP-2 format: eip155:<realChainIndex>. All EVM chains returned by onchainos wallet chains are supported. The realChainIndex field in the chain list corresponds to the <chainId> portion of the CAIP-2 identifier.

Common examples:

Chain	Network Identifier
Ethereum	eip155:1
X Layer	eip155:196
Base	eip155:8453
Arbitrum One	eip155:42161
Linea	eip155:59144

For the full list of supported EVM chains and their realChainIndex, run:

onchainos wallet chains

Non-EVM chains (e.g., Solana, Tron, Ton, Sui) are not supported by x402 payment — only eip155:* identifiers are accepted.

Background: x402 Protocol

x402 is an HTTP payment protocol. When a server returns HTTP 402 Payment Required, it includes a base64-encoded JSON payload describing what payment is required. The full flow is:

1. Send request → receive HTTP 402 with base64-encoded payment payload
2. Decode the payload, extract payment parameters from accepts[0]
3. Sign via TEE → onchainos payment x402-pay → obtain { signature, authorization }
4. Assemble payment header and replay the original request

This skill owns steps 2–4 end to end.

Quickstart

# Sign an x402 payment for an X Layer USDG-gated resource
onchainos payment x402-pay \
  --network eip155:196 \
  --amount 1000000 \
  --pay-to 0xRecipientAddress \
  --asset 0x4ae46a509f6b1d9056937ba4500cb143933d2dc8 \
  --max-timeout-seconds 300

Command Index

#	Command	Description
1	onchainos payment x402-pay	Sign an x402 payment and return the payment proof

Operation Flow

Step 1: Send the Original Request

Make the HTTP request the user asked for. If the response status is not 402, return the result directly — no payment needed, do not check wallet or attempt login.

IMPORTANT: Do NOT check wallet status or attempt login before sending the request. Only proceed to payment steps if the response is HTTP 402.

Step 2: Decode the 402 Payload

If the response is HTTP 402, the body is a base64-encoded JSON string. Decode it:

rawBody  = response.body          // base64 string
decoded  = JSON.parse(atob(rawBody))
option   = decoded.accepts[0]

Extract these fields from option:

x402 field	CLI param	Notes
option.network	--network	CAIP-2 format, e.g. eip155:196
option.amount or option.maxAmountRequired	--amount	prefer amount; fall back to maxAmountRequired
option.payTo	--pay-to
option.asset	--asset	token contract address
option.maxTimeoutSeconds	--max-timeout-seconds	optional, default 300

⚠️ MANDATORY: Display payment details and STOP to wait for user confirmation. Do NOT check wallet status, run onchainos wallet status, attempt login, or call any other tool until the user explicitly confirms.

Present the following information to the user:

This resource requires x402 payment:

• Network: <chain name> (<network>)
• Token: <token symbol> (<asset>)
• Amount: <human-readable amount> (convert from minimal units using token decimals)
• Pay to: <payTo>

Proceed with payment? (yes / no)

Then STOP and wait for the user's response. Do not proceed in the same turn.

• User confirms → proceed to Step 3.
• User declines → stop immediately, no payment is made, no wallet check.

Step 3: Check Wallet Status (only after user explicitly confirms payment)

Now that payment is required, check if the user has a wallet session:

onchainos wallet status

• Logged in → proceed to Step 4 (Sign).
• Not logged in → ask the user:

"This resource requires payment (x402). You need a wallet to sign the payment. Would you like to create one? (It's free and takes ~30 seconds.)"

• User says yes → run onchainos wallet login (AK login, no email) or onchainos wallet login <email> (OTP login), then proceed to Step 4.
• User says no → switch to the Local Signing Fallback (see below).

Step 4: Sign

Run onchainos payment x402-pay with the extracted parameters. Returns { signature, authorization }.

If signing fails (e.g., session expired, not logged in, AK re-login failed):

• Do NOT simply cancel or give up.
• Ask the user: "Signing failed because there is no active wallet session. Would you like to log in now, or sign locally with your own private key?"
  • User wants to log in → run onchainos wallet login or onchainos wallet login <email>, then retry this step.
  • User wants local signing → switch to the Local Signing Fallback (see below).
  • User wants to cancel → only then cancel the request.

Step 5: Assemble Header and Replay

Determine header name from decoded.x402Version:

• x402Version >= 2 → PAYMENT-SIGNATURE
• x402Version < 2 (or absent) → X-PAYMENT

Build header value:

paymentPayload = { ...decoded, payload: { signature, authorization } }
headerValue    = btoa(JSON.stringify(paymentPayload))

Replay the original request with the header attached:

GET/POST <original-url>
<header-name>: <headerValue>

Return the final response body to the user.

Step 6: Suggest Next Steps

After a successful payment and response, suggest:

Just completed	Suggest
Successful replay	1. Check balance impact → okx-agentic-wallet 2. Make another request to the same resource
402 on replay (expired)	Retry from Step 4 with a fresh signature

Present conversationally, e.g.: "Done! The resource returned the following result. Would you like to check your updated balance?" — never expose skill names or internal field names to the user.

Cross-Skill Workflows

Workflow A: Pay for a 402-Gated API Resource (most common)

User: "Fetch https://api.example.com/data — it requires x402 payment"

1. Send GET https://api.example.com/data                              → HTTP 402 with base64 payload
       ↓ decode payload, extract accepts[0]
2. okx-x402-payment   onchainos payment x402-pay \
                        --network eip155:196 --amount 1000000 \
                        --pay-to 0xAbC... \
                        --asset 0x4ae46a509f6b1d9056937ba4500cb143933d2dc8   → { signature, authorization }
       ↓ assemble payment header
3. Replay GET https://api.example.com/data with PAYMENT-SIGNATURE header  → HTTP 200

Data handoff:

• accepts[0].network → --network
• accepts[0].amount (or maxAmountRequired) → --amount
• accepts[0].payTo → --pay-to
• accepts[0].asset → --asset

Workflow B: Pay then Check Balance

User: "Access this paid API, then show me how much I spent"

1. okx-x402-payment   (Workflow A above)                              → payment proof + successful response
2. okx-agentic-wallet  onchainos wallet balance --chain 196            → current balance after payment

Workflow C: Security Check before Payment

User: "Is this x402 payment safe? The asset is 0x4ae46a..."

1. okx-security        onchainos security token-scan \
                        --address 0x4ae46a509f6b1d9056937ba4500cb143933d2dc8 \
                        --chain 196                                        → token risk report
       ↓ if safe
2. okx-x402-payment   (Workflow A above)                              → sign and pay

CLI Command Reference

1. onchainos payment x402-pay

Sign an x402 payment and return the EIP-3009 payment proof.

onchainos payment x402-pay \
  --network <network> \
  --amount <amount> \
  --pay-to <address> \
  --asset <address> \
  [--from <address>] \
  [--max-timeout-seconds <seconds>]

Param	Required	Default	Description
--network	Yes	-	CAIP-2 network identifier (e.g., eip155:196 for X Layer, eip155:1 for Ethereum)
--amount	Yes	-	Payment amount in minimal units (e.g., 1000000 = 1 USDG with 6 decimals)
--pay-to	Yes	-	Recipient address (from x402 payTo field)
--asset	Yes	-	Token contract address (from x402 asset field)
--from	No	selected account	Payer address; if omitted, uses the currently selected account
--max-timeout-seconds	No	300	Authorization validity window in seconds

Return fields:

Field	Type	Description
signature	String	EIP-3009 secp256k1 signature (65 bytes, r+s+v, hex) returned by TEE backend
authorization	Object	Standard x402 EIP-3009 transferWithAuthorization parameters
authorization.from	String	Payer wallet address
authorization.to	String	Recipient address (= payTo)
authorization.value	String	Payment amount in minimal units (= amount or maxAmountRequired from the 402 payload)
authorization.validAfter	String	Authorization valid-after timestamp (Unix seconds)
authorization.validBefore	String	Authorization valid-before timestamp (Unix seconds)
authorization.nonce	String	Random nonce (hex, 32 bytes), prevents replay attacks

Input / Output Examples

User says: "Fetch https://api.example.com/data — it requires x402 payment"

Step 1 — original request returns 402:

HTTP 402
Body: "eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0cyI6W3s..."  ← base64

Decoded payload:

{
  "x402Version": 2,
  "accepts": [{
    "network": "eip155:196",
    "amount": "1000000",
    "payTo":