onchainos

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

   .

• 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

--network

eip155:<realChainIndex>

onchainos wallet chains

realChainIndex

<chainId>

eip155:1

eip155:196

eip155:8453

eip155:42161

eip155:59144

realChainIndex

onchainos wallet chains

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

eip155:*

identifiers are accepted.

HTTP 402 Payment Required

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

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

HTTP 402

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

option

option.network

--network

eip155:196

option.amount

option.maxAmountRequired

--amount

amount

maxAmountRequired

option.payTo

--pay-to

option.asset

--asset

option.maxTimeoutSeconds

--max-timeout-seconds

onchainos wallet status

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)

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

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

onchainos payment x402-pay

{ signature, authorization }

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

decoded.x402Version

• x402Version >= 2

  →

  PAYMENT-SIGNATURE

• x402Version < 2

  (or absent) →

  X-PAYMENT

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

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

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

• accepts[0].network

  →

  --network

• accepts[0].amount

  (or

  maxAmountRequired

  ) →

  --amount

• accepts[0].payTo

  →

  --pay-to

• accepts[0].asset

  →

  --asset

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

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

• User has a local private key (e.g., in a

  .env

  file, hardware wallet, or MetaMask export)
• The payer address must hold sufficient ERC-20 balance of the

  asset

  token on the target chain
• The

  asset

  token contract must support EIP-3009

  transferWithAuthorization

TransferWithAuthorization

eth_signTypedData_v4

from

to

option.payTo

value

option.amount

validAfter

"0"

validBefore

now + maxTimeoutSeconds

nonce

name()

version

"1"

"2"

chainId

verifyingContract

option.asset

const wallet = new ethers.Wallet('<PRIVATE_KEY>');
const signature = await wallet.signTypedData(domain, types, message);

See EIP-3009 for the full typed data spec.

domain.name

/

version

vary per token (e.g. USDC uses

"USD Coin"

/

"2"

) — query the contract to confirm.

• The private key never leaves the local machine — signing is done entirely offline
• The

  nonce

  must be a random 32-byte hex value; reusing a nonce will cause the transaction to be rejected

• validBefore

  is a Unix timestamp in seconds — set it to

  now + maxTimeoutSeconds

  (default 300s / 5 minutes)
• If the token uses a non-standard EIP-712 domain (e.g., different

  version

  string), the signature will be invalid — always query the contract first
• The signed authorization only authorizes the exact

  (from, to, value, nonce)

  tuple — it cannot be modified or reused

• Not logged in: Ask user if they want to create a wallet (

  onchainos wallet login

  or

  onchainos wallet login <email>

  ). If not, guide them through the Local Signing Fallback above
• Unsupported network: Only EVM chains with CAIP-2

  eip155:<chainId>

  format are supported
• No wallet for chain: The logged-in account must have an address on the requested chain; if not, inform the user
• Amount in wrong units:

  --amount

  must be in minimal units — remind user to convert (e.g., 1 USDG =

  1000000

  for 6 decimals)
• Expired authorization: If the server rejects the payment as expired, retry with a fresh signature
• Network error: Retry once, then prompt user to try again later

• --amount

  is always in minimal units (e.g.,

  1000000

  for 1 USDG)
• When displaying to the user, convert to UI units: divide by

  10^decimal

• Show token symbol alongside (e.g.,

  1.00 USDG

  )

• Primary path (

  onchainos payment x402-pay

  ): requires an authenticated JWT session; signing is performed inside a TEE — the private key never leaves the secure enclave
• Fallback path (local signing): requires the user's own private key; signing is done entirely on the local machine — no JWT or TEE needed
• This skill only signs — it does not broadcast or deduct balance directly; payment settles when the recipient redeems the authorization on-chain

• --network

  must be CAIP-2 format:

  eip155:<chainId>

  (e.g.,

  eip155:1

  ,

  eip155:8453

  ,

  eip155:196

  )
• The returned

  authorization

  object must be included alongside

  signature

  when building the payment header