Integrating OKX Security Scan: Pre-Signature Blocking and Failure Fallback

OKX

23 October 2026

Integrating OKX security scan for pre-signature blocking is not about "scanning to pass". The core logic is to treat the action field returned by the scan as a hard switch. OKX Onchain OS's security skill (okx-security) returns three types of actions for transaction and signature scans: block, warn, and safe (empty value). block means your application must refuse to continue. You cannot show a "Continue Anyway" button for the user to click. warn requires explicit user confirmation. The key judgment for failure fallback is: scan failure does not equal pass. On network timeout, rate limiting, or malformed response, the default behavior should be to ask the user whether to retry, not to silently allow the action.

OKX Exchange
A leading global cryptocurrency platform,suitable for both beginners and experienced traders.
New user benefit: 20% off trading fees upon registration!！

Pre-Signature Blocking: tx-scan or sig-scan

tx-scan is used for security checks before transaction execution and covers EVM and Solana. sig-scan specifically checks message signature requests and currently only supports EVM, covering EIP-712 and personal_sign types. If your application blocks before the user signs a transaction, call tx-scan. If you are blocking message signatures like login verification or authorization permits (such as Permit2), use sig-scan.

The return structure of both commands is the same: the top-level action field reflects the highest priority risk item in riskItemDetail. The priority order is block > warn empty value/safe. Your code should only read this top-level action. Do not parse the underlying riskLevel or boolean tags to re-evaluate the result yourself—the CLI has already done the classification. Recalculating on the client side will deviate from the official matrix.

block corresponds to high risk. The behavior is do not execute, show details, and suggest cancellation. warn corresponds to medium risk. The behavior is to show risk details and require the user to give an explicit yes/no confirmation. An empty value or safe only means no risk was detected under the premise that the scan completed successfully. It cannot be directly equated with "secure".

Failure Fallback: An Incomplete Scan Is Not a Pass

This is the easiest place to make mistakes during integration. The fail-safe principle of the official security skill is very clear: if the scan fails to complete due to a network error, timeout, rate limit, or malformed response format, your application must do three things: report the error to the user, ask whether to retry or continue without scanning, and if the user chooses to continue, display a warning and log the skipped scan.

A specific implementation judgment: wrap the scan call in a try/catch block. The catch branch must not default to returning safe or skipping the block. The correct approach is to throw a state that requires a user decision. If the user insists on continuing, leave a record in the logs for later tracing. This is different from handling action: warn. warn means the scan completed and found medium risk. Scan failure means no result was obtained at all. Both require user confirmation, but the prompt text should be different—the former says "Risk found, do you want to continue?", while the latter says "Unable to complete security check, do you want to continue without verification?".

Another detail: if the warnings field returned by the scan is not empty, it means the scan completed but some data may be incomplete. In this case, you should still display the existing risk information instead of ignoring the entire result because warnings exists.

An Easy Point of Confusion: `token-scan` Is Not Signature Blocking

token-scan is used for token risk detection (honeypots, tax rates, liquidity, etc.). Its action values are block / pause / warn / safe, which are not exactly the same as the block / warn / safe from tx-scan/sig-scan. In token-scan, pause corresponds to a high-risk buy scenario and requires explicit user confirmation. warn corresponds to medium risk and the user can continue after seeing the prompt. If you are doing a token-level pre-check before signing (for example, the user wants to buy an unfamiliar token), use token-scan and pass --trade-direction buy. If you are checking the transaction itself (recipient address, call data, approval amount), use tx-scan. Do not use the action from token-scan to decide whether a transaction can be signed. Their semantics and matrices are different.

Practical Writing of the Fallback Strategy

The recommended approach is: default to blocking when the scan fails, rather than defaulting to allowing. Although the official documentation has one exception in the swap scenario—token-scan failure automatically continues with a warning to avoid blocking time-sensitive transactions—this exception has a clear scenario limit (swap context) and is not a general rule. For pre-signature blocking, there is no reason to automatically allow an action when the scan has not finished running.

If your application targets regular users, the warn confirmation interface needs to explain the risk clearly, not just pop up a "Do you want to continue?" message. In OKX's label catalog, warn may correspond to medium risks such as mintable, having freeze authority, or not renouncing ownership. It may also be a composite analysis flag with no specific label. Showing the user the list of risk labels returned directly by the CLI (without the level prefix) is more useful than a vague "There is risk" message.