--- title: "Scan Transaction" method: POST path: "/v0/bitcoin/transaction-raw/scan" tags: ["Bitcoin"] --- # Scan Transaction `POST /v0/bitcoin/transaction-raw/scan` Scan a raw Bitcoin transaction for security risks before signing. Returns a validation verdict (Benign, Warning, or Malicious) and, when requested, a simulation of asset changes. ## Request body - BitcoinTransactionScanRequest - `chain` 'bitcoin', required - `options` BitcoinOptions[] — Which parts of the response you need: - **validation** — Security verdict (Benign/Warning/Malicious) and risk explanation. Use when deciding whether to block or warn. - **simulation** — Predicted summary of balance and asset changes (e.g. "You will send 0.01 BTC to bc1q..."). Use when showing the user what the transaction does. You can request one or both; default is both. - `account_address` string, required — The Bitcoin address that owns the UTXOs being spent. - `transaction` string, required — The raw unsigned transaction in hexadecimal, as produced by the wallet or your app. This is the same payload the user would sign. - `metadata` union, required — Context of where the transaction was initiated: use wallet metadata when the user is signing in a wallet for an external site; use in-app metadata when the transaction is created within your own app. Choosing the correct type improves risk analysis and reporting. - BitcoinWalletRequestMetadata - `type` 'wallet', required — Identifies the request as a wallet signing a transaction on behalf of an external dApp. The type improves threat context and helps attribute risk to specific origins. - `url` string, required — The full URL of the dApp or page where the user initiated the transaction (e.g. https://app.example.com/swap). - `account` RoutersChainAgnosticModelsRequestAccount - `account_id` string, required — Unique identifier for the account. - `account_creation_timestamp` string, date-time — Timestamp when the account was created. - `user_age` integer — Age of the user in years - `user_country_code` string — ISO country code of the user's location. - `account_addresses` string[] — List of all account addresses in different chains based on the CAIPs standard (https://github.com/ChainAgnostic/CAIPs). Ethereum mainnet example: eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb - `connection` RoutersChainAgnosticModelsRequestConnection - `user_agent` string — User agent string from the client's browser or application. - `ip_address` string, ipvanyaddress, required — IP address of the customer making the request. Both IPv4 and IPv6 addresses are supported. - `origin` string, uri — The full URL of the website that the request was directed to. - `walletconnect_name` string — WalletConnect session name, when the request originates from a WalletConnect session. - `walletconnect_description` string — WalletConnect session description, when the request originates from a WalletConnect session. - `non_dapp` boolean, nullable — Indicates that the transaction was not initiated by a dapp. Use false when the transaction is from a dapp. - BitcoinInAppRequestMetadata - `type` 'in_app' — Identifies the request as coming from your own app (e.g. in-app send, swap, or internal flow). - `account` RoutersChainAgnosticModelsRequestAccount - `account_id` string, required — Unique identifier for the account. - `account_creation_timestamp` string, date-time — Timestamp when the account was created. - `user_age` integer — Age of the user in years - `user_country_code` string — ISO country code of the user's location. - `account_addresses` string[] — List of all account addresses in different chains based on the CAIPs standard (https://github.com/ChainAgnostic/CAIPs). Ethereum mainnet example: eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb - `connection` RoutersChainAgnosticModelsRequestConnection - `user_agent` string — User agent string from the client's browser or application. - `ip_address` string, ipvanyaddress, required — IP address of the customer making the request. Both IPv4 and IPv6 addresses are supported. - `origin` string, uri — The full URL of the website that the request was directed to. - `walletconnect_name` string — WalletConnect session name, when the request originates from a WalletConnect session. - `walletconnect_description` string — WalletConnect session description, when the request originates from a WalletConnect session. - `non_dapp` boolean, nullable — Indicates that the transaction was not initiated by a dapp. Use false when the transaction is from a dapp. ## Response `200` Successful response with validation verdict and, if requested, simulation of asset changes. For more information about responses, see the [full response reference](/api-reference/end-user-protection/transaction-scanning/bitcoin/bitcoin-transaction-scanning-response-reference). Note: HTTP 200 indicates the request was processed. Always check `validation.status` and `simulation.status` (when present), which may be `Error` with an `error` message (e.g. simulation failing due to invalid UTXOs). - BitcoinTransactionScanResponse - `simulation` union — Simulation result; Only present if simulation option is included in the request - BitcoinSimulationResult - `status` 'Success', required - `assets_diffs` object — Per-account list of asset balance changes (native, inscriptions, runes) for the simulated transaction. - `address_details` BitcoinAddressDetailsBaseSchemaAnnotatedNewTypeSkipValidationPlainSerializerGetPydanticSchema[] — Details of addresses involved in the transaction. - `account_address` string, required — Encoded public key of the account - `description` string, nullable — Description of the account - `account_summary` BitcoinAccountSummary, required - `account_assets_diffs` union[] — Per-asset balance changes (native BTC, inscriptions, runes) for the requested account. - union - BitcoinNativeAssetDiff - … - BitcoinInscriptionAssetDiff - … - BitcoinRunesAssetDiff - … - `total_usd_diff` BitcoinTotalUsdDiffSchema, required - `in` number, required — Total incoming USD transfers. - `out` number, required — Total outgoing USD transfers. - `total` number — Total USD transfers. - BitcoinSimulationErrorSchema - `status` 'Error', required - `error` string, required — Error message - `validation` union - BitcoinValidationResult - `status` 'Success', required - `result_type` 'Benign' | 'Warning' | 'Malicious', required - `description` string, required — A textual description about the validation result. - `reason` string, required — Human-readable explanation of why the transaction received the given `result_type` verdict. - `classification` string, required — A textual classification that can be presented to the user explaining the reason. - `features` BitcoinValidationFeature[], required — List of validation findings (addresses and classifications) that contributed to the verdict. - `type` 'Benign' | 'Warning' | 'Malicious' | 'Info', required - `feature_id` string, required — Unique identifier for this type of finding. - `description` string, required — Human-readable explanation of this finding. - `address` string, required — Bitcoin address that this finding is associated with. - BitcoinValidationErrorSchema - `status` 'Error', required - `error` string, required — Error message ## Other responses - `422` — Request validation failed (e.g. missing or invalid request body fields). --- [API](https://skmtc.net/blockaid-official/apis/blockaid-api.md) · [All operations](https://skmtc.net/blockaid-official/apis/blockaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/blockaid-official/blockaid-api/versions/17c41f337b2e/schema)