Onchain OS Security

5 commands for token risk analysis, DApp phishing detection, transaction pre-execution security, signature safety, and approval management.

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

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

1. 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: INLINECODE41

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

1. 5. Do NOT auto-reinstall on command failures. Report errors and suggest

onchainos --version or manual reinstall from https://github.com/okx/onchainos-skills.

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

Fail-safe Principle (CRITICAL)

Scan completed — risk detected

If a security scan completes successfully and returns action: "block" or action: "warn", follow the Risk Action Priority Rule below. The Agent MUST NOT override risk verdicts.

Scan failed — infrastructure error

If a security scan fails to complete (network error, API timeout, rate limiting, malformed response), the Agent MUST:

• - Report the error clearly to the user.
• Ask the user whether to retry the scan or proceed without scan results.
• If the user chooses to proceed, display a warning:

> "⚠️ Security scan could not be completed. Proceeding without verification — please ensure you trust this operation."

• - Log the skipped scan for auditability.

A security scan that fails to complete is NOT a "pass". Always inform the user and let them make an explicit decision.

Risk Action Priority Rule

INLINECODE50 > warn > safe (empty). The top-level action field reflects the highest priority from riskItemDetail.

INLINECODE54 value	Risk Level	Agent Behavior
(empty/null)	Low risk	Safe to proceed
INLINECODE55

Medium risk | Show risk details, ask for explicit user confirmation |
| block | High risk | Do NOT proceed, show risk details, recommend cancel |

• - Risk scan result is still valid even if simulation fails (simulator.revertReason may contain the revert reason).
• If warnings field is populated, the scan completed but some data may be incomplete. Still present available risk information.
• An empty/null action in a successful API response means "no risk detected". But if the API call failed, the absence of action does NOT mean safe — apply the fail-safe principle.

Security commands do not require wallet login. They work with any address.

Chain Name Support

The CLI accepts human-readable chain names and resolves them automatically.

Chain	Name	chainIndex
XLayer	INLINECODE61	INLINECODE62
Ethereum

ethereum or eth | 1 |
| Solana | solana or sol | 501 |
| BSC | bsc or bnb | 56 |
| Polygon | polygon or matic | 137 |
| Arbitrum | arbitrum or arb | 42161 |
| Base | base | 8453 |
| Avalanche | avalanche or avax | 43114 |
| Optimism | optimism or op | 10 |
| zkSync Era | zksync | 324 |
| Linea | linea | 59144 |
| Scroll | scroll | 534352 |

Address format note: EVM addresses (0x...) work across Ethereum/BSC/Polygon/Arbitrum/Base etc. Solana addresses (Base58) and Bitcoin addresses (UTXO) have different formats. Do NOT mix formats across chain types.

Command Index

#	Command	Description
1	INLINECODE93	Token risk / honeypot detection (all chains)
2

onchainos security dapp-scan | DApp / URL phishing detection (chain-agnostic) | | 3 | onchainos security tx-scan | Transaction pre-execution security (EVM + Solana) | | 4 | onchainos security sig-scan | Message signature security (EVM only) | | 5 | onchainos security approvals | Token approval / Permit2 authorization query (EVM only) |

Reference Loading Rules (MANDATORY)

Before executing ANY security command, you MUST read the corresponding reference document from skills/okx-security/references/. Do NOT rely on prior knowledge — always load the reference first.

User intent	Read this file FIRST
Token safety, honeypot, is this token safe, 代币安全, 蜜罐检测, 貔貅盘	INLINECODE99
DApp/URL phishing, is this site safe, 钓鱼网站

references/risk-domain-detection.md |
| Transaction safety, tx pre-execution, signature safety, approve safety, 交易安全, 签名安全 | references/risk-transaction-detection.md |
| Approvals, allowance, Permit2, revoke, 授权管理, 授权查询, 风险授权 | references/risk-approval-monitoring.md |

When a workflow involves multiple commands (e.g., token-scan then tx-scan), load each reference before executing that command.

Integration with Other Skills

Security scanning is often a prerequisite for other wallet operations:

• - Before wallet send with a contract token: run token-scan to verify token safety
• Before wallet contract-call with approve calldata: run tx-scan to check spender
• Before interacting with any DApp URL: run INLINECODE107
• Before signing any EIP-712 message: run INLINECODE108

Use okx-agentic-wallet skill for the subsequent send/contract-call operations.