openapi: 3.1.0
info:
  title: Blockaid Asset Management Crypto Fraud Prevention API
  description: Blockaid Risk Score API
  termsOfService: https://www.blockaid.io/legal/terms-of-use
  license:
    name: Proprietary
    url: https://www.blockaid.io/legal
  version: 1.0.0
servers:
- url: https://api.blockaid.io
  description: Production server
- url: https://client.blockaid.io
  description: Clients server
tags:
- name: Crypto Fraud Prevention
paths:
  /v0/transaction/scan:
    post:
      tags:
      - Crypto Fraud Prevention
      summary: Scan Transaction
      description: Gets a transaction and returns a full security assessment indicating whether or not the transaction is malicious, along with textual reasons explaining why it was flagged as such.
      operationId: scan-transaction-chain-agnostic
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionScanRequest'
            examples:
              Bitcoin Malicious Transaction:
                summary: Bitcoin - Malicious Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: bitcoin
                    transaction_action: withdrawal
                    asset:
                      symbol: BTC
                    to: bc1qanrfutwqh854g74lqrygr55jkgf99em4lpfm80
                    amount: 1
                  metadata:
                    account:
                      account_id: '1'
                    connection:
                      user_agent: '1'
                      ip_address: 1.1.1.1
              Bitcoin High Risk Transaction:
                summary: Bitcoin - High Risk Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: bitcoin
                    transaction_action: withdrawal
                    asset:
                      symbol: BTC
                    to: bc1qvn5pv6rwn9ps3m8rwfm2ffg6wc4hnzve9mgem5
                    amount: 1
                  metadata:
                    connection:
                      user_agent: '1'
                      ip_address: 1.1.1.1
              Bitcoin Warning Transaction:
                summary: Bitcoin - Warning Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: bitcoin
                    asset:
                      symbol: BTC
                    to: 19rioPBg9n8TXobb2rKzwxM71jgArShVPd
                    amount: 1
                  metadata:
                    connection:
                      user_agent: '1'
                      ip_address: 1.1.1.1
              Bitcoin Benign Transaction:
                summary: Bitcoin - Benign Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: bitcoin
                    transaction_action: withdrawal
                    asset:
                      symbol: BTC
                    to: 3Eif1JfqeMERRsQHtvGEacNN9hhuvnsfe9
                    amount: 1
                  metadata:
                    connection:
                      user_agent: '1'
                      ip_address: 1.1.1.1
              Ethereum Malicious Transaction:
                summary: Ethereum - Malicious Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: ethereum
                    transaction_action: withdrawal
                    asset:
                      symbol: ETH
                    to: '0x0a5738064da9dda3cf4a4ae8d8e49b16fd7467c5'
                    amount: 1
                  metadata:
                    account:
                      account_id: '1'
              Ethereum High Risk Transaction:
                summary: Ethereum - High Risk Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: ethereum
                    transaction_action: withdrawal
                    asset:
                      symbol: ETH
                    to: '0x6174307e0eea8e26a62240b2b8b5d32d7edb0203'
                    amount: 1
                  metadata:
                    account:
                      account_id: '1'
              Ethereum Warning Transaction:
                summary: Ethereum - Warning Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: ethereum
                    transaction_action: withdrawal
                    asset:
                      symbol: ETH
                    to: '0x3b60e3a06af5aa4da178aade658211a0d3f51222'
                    amount: 1
                  metadata:
                    account:
                      account_id: '1'
              Solana Malicious Transaction:
                summary: Solana - Malicious Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: solana
                    transaction_action: withdrawal
                    asset:
                      symbol: SOL
                    to: 6KH26MJdg4YNrNezy6wDwK5Mn3whNo6nn12nVcyzHF7
                    amount: 1
                  metadata:
                    account:
                      account_id: '1'
              Solana High Risk Transaction:
                summary: Solana - High Risk Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: solana
                    asset:
                      symbol: SOL
                    to: 7Hm7NmPko67CSFv846MH5VWAWKBJYDb3rxBcC1mnQa2E
                    amount: 1
                  metadata:
                    account:
                      account_id: '1'
              Solana Warning Transaction:
                summary: Solana - Warning Transaction
                value:
                  options:
                  - validation
                  data:
                    chain: solana
                    transaction_action: withdrawal
                    asset:
                      symbol: SOL
                    to: uB7ett5PHb6WFxdcvyHuxPbBhmACFg9xbztL2iw4w9X
                    amount: 1
                  metadata:
                    account:
                      account_id: '1'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: false
      security:
      - APIKey: []
      - ClientID: []
components:
  schemas:
    TransactionFeature:
      properties:
        entity:
          type: string
          enum:
          - transaction
          title: Entity
          description: Type of entity associated with the feature
          default: transaction
        type:
          allOf:
          - $ref: '#/components/schemas/routers__chain_agnostic__models__response__FeatureType'
          description: Type of feature detected in the transaction scan
        feature_id:
          type: string
          title: Feature Id
          description: Unique identifier for the detected feature
        description:
          type: string
          title: Description
          description: Detailed description of the detected feature
      type: object
      required:
      - type
      - feature_id
      - description
      title: TransactionFeature
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Data:
      properties:
        chain:
          allOf:
          - $ref: '#/components/schemas/Chains'
          description: Blockchain network where the transaction will be executed
        transaction_action:
          type: string
          enum:
          - deposit
          - withdrawal
          title: Transaction Action
          description: Action the transaction is making
        from:
          type: string
          title: From
          description: Source address or identifier for the transaction
        to:
          type: string
          title: To
          description: Destination address or identifier for the transaction
        amount:
          type: number
          exclusiveMinimum: 0.0
          title: Amount
          description: Amount of the transaction in the specified asset
        asset:
          anyOf:
          - $ref: '#/components/schemas/AssetAddress'
          - $ref: '#/components/schemas/AssetSymbol'
          title: Asset
          description: Asset information
      type: object
      required:
      - chain
      - to
      - amount
      - asset
      title: Data
    AddressFeature:
      properties:
        entity:
          type: string
          enum:
          - address
          title: Entity
          description: Type of entity associated with the feature
          default: address
        type:
          allOf:
          - $ref: '#/components/schemas/routers__chain_agnostic__models__response__FeatureType'
          description: Type of feature detected in the address scan
        feature_id:
          type: string
          title: Feature Id
          description: Unique identifier for the detected feature
        description:
          type: string
          title: Description
          description: Detailed description of the detected feature
        address:
          type: string
          title: Address
          description: The blockchain address where the feature was detected
        associated_urls:
          items:
            type: string
          type: array
          title: Associated Urls
          description: List of URLs associated with this address
      type: object
      required:
      - type
      - feature_id
      - description
      - address
      - associated_urls
      title: AddressFeature
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    routers__chain_agnostic__models__response__FeatureType:
      type: string
      enum:
      - Malicious
      - Warning
      - Benign
      - High-Risk
      - Info
      title: FeatureType
      description: The type of feature detected in the scan.
    UrlFeature:
      properties:
        entity:
          type: string
          enum:
          - url
          title: Entity
          description: Type of entity associated with the feature
          default: url
        type:
          allOf:
          - $ref: '#/components/schemas/routers__chain_agnostic__models__response__FeatureType'
          description: Type of feature detected in the URL scan
        feature_id:
          type: string
          title: Feature Id
          description: Unique identifier for the detected feature
        description:
          type: string
          title: Description
          description: Detailed description of the detected feature
        url:
          type: string
          title: Url
          description: The URL where the feature was detected
      type: object
      required:
      - type
      - feature_id
      - description
      - url
      title: UrlFeature
    routers__chain_agnostic__models__response__ValidationResultType:
      type: string
      enum:
      - Malicious
      - Warning
      - Benign
      - High-Risk
      title: ValidationResultType
      description: The type of validation result.
    AssetAddress:
      properties:
        address:
          type: string
          title: Address
          description: The address of the asset
      type: object
      required:
      - address
      title: AssetAddress
    Options:
      type: string
      enum:
      - validation
      title: Options
      description: Requested output section to include in the response.
    ScanResult:
      properties:
        validation:
          allOf:
          - $ref: '#/components/schemas/ValidationResult'
          title: Validation
          description: Complete validation result containing all scan details and findings
        platform_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Url
          description: Deep-link URL to the Blockaid platform address overview page for the scanned `to` address. Null if no URL is available for the given chain.
      type: object
      required:
      - validation
      title: ScanResult
    TransactionScanStatus:
      type: string
      enum:
      - Success
      - Error
      title: TransactionScanStatus
      description: The status of the transaction scan
    Chains:
      type: string
      enum:
      - arbitrum
      - avalanche
      - base
      - base-sepolia
      - bsc
      - ethereum
      - ethereum-sepolia
      - optimism
      - polygon
      - zksync
      - zksync-sepolia
      - zora
      - linea
      - blast
      - scroll
      - avalanche-fuji
      - degen
      - gnosis
      - worldchain
      - soneium-minato
      - ronin
      - apechain
      - berachain
      - ink-sepolia
      - ink
      - abstract
      - abstract-testnet
      - metacade
      - metacade-testnet
      - soneium
      - unichain
      - lordchain-testnet
      - lordchain
      - sei
      - flow-evm
      - hyperevm
      - megaeth
      - katana
      - plume
      - solana
      - bitcoin
      - xlayer
      - monad
      - monad-testnet
      - tron
      - kaia
      - plasma
      - mantle
      - robinhood
      - arc
      title: Chains
      description: The chain name
    ScanRequestMetadata:
      properties:
        domain:
          type: string
          title: Domain
          description: The full URL of the DApp or website that initiated the request, for cross-reference. Must use the https or http scheme and contain a valid hostname. Cannot contain JSON, braces, or other embedded data structures.
        non_dapp:
          type: boolean
          title: Non Dapp
          description: Set to true when the request was not initiated by a dapp. Dapp requests should provide the `domain` field.
        account:
          allOf:
          - $ref: '#/components/schemas/routers__chain_agnostic__models__request__Account'
          title: Account
          description: End-user account context (id, age, country, creation time, and account_addresses).
        connection:
          allOf:
          - $ref: '#/components/schemas/routers__chain_agnostic__models__request__Connection'
          title: Connection
          description: Connection metadata including user agent, IP information, and origin.
      type: object
      title: ScanRequestMetadata
    AssetSymbol:
      properties:
        symbol:
          type: string
          title: Symbol
          description: The symbol of the asset
      type: object
      required:
      - symbol
      title: AssetSymbol
    routers__chain_agnostic__models__request__Account:
      properties:
        account_id:
          type: string
          title: Account Id
          description: Unique identifier for the account.
        account_creation_timestamp:
          type: string
          format: date-time
          title: Account Creation Timestamp
          description: Timestamp when the account was created.
        user_age:
          type: integer
          exclusiveMinimum: 0.0
          title: User Age
          description: Age of the user in years
        user_country_code:
          type: string
          title: User Country Code
          description: ISO country code of the user's location.
        account_addresses:
          items:
            type: string
          type: array
          title: Account Addresses
          description: 'List of all account addresses in different chains based on the CAIPs standard (https://github.com/ChainAgnostic/CAIPs). Ethereum mainnet example: eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb'
      type: object
      required:
      - account_id
      title: Account
    routers__chain_agnostic__models__request__Connection:
      properties:
        user_agent:
          type: string
          title: User Agent
          description: User agent string from the client's browser or application.
        ip_address:
          type: string
          format: ipvanyaddress
          title: Ip Address
          description: IP address of the customer making the request. Both IPv4 and IPv6 addresses are supported.
        origin:
          type: string
          minLength: 1
          format: uri
          title: Origin
          description: The full URL of the website that the request was directed to.
        walletconnect_name:
          type: string
          title: Walletconnect Name
          description: WalletConnect session name, when the request originates from a WalletConnect session.
        walletconnect_description:
          type: string
          title: Walletconnect Description
          description: WalletConnect session description, when the request originates from a WalletConnect session.
      type: object
      required:
      - ip_address
      title: Connection
    ValidationResult:
      properties:
        status:
          allOf:
          - $ref: '#/components/schemas/TransactionScanStatus'
          description: Status indicating whether the transaction scan was successful or encountered an error
        result_type:
          allOf:
          - $ref: '#/components/schemas/routers__chain_agnostic__models__response__ValidationResultType'
          description: Type of validation result indicating the severity of findings
        classification:
          type: string
          title: Classification
          description: Classification of the scan result based on the detected features
        description:
          type: string
          title: Description
          description: Detailed description of the validation result
        features:
          items:
            anyOf:
            - $ref: '#/components/schemas/AddressFeature'
            - $ref: '#/components/schemas/UrlFeature'
            - $ref: '#/components/schemas/TransactionFeature'
          type: array
          title: Features
          description: List of features detected during the scan
          default: []
      type: object
      required:
      - status
      - result_type
      - classification
      - description
      title: ValidationResult
    TransactionScanRequest:
      properties:
        options:
          items:
            $ref: '#/components/schemas/Options'
          type: array
          description: List of options to apply during the transaction scan
        data:
          allOf:
          - $ref: '#/components/schemas/Data'
          title: Data
          description: Transaction data
        metadata:
          allOf:
          - $ref: '#/components/schemas/ScanRequestMetadata'
          title: Metadata
          description: Additional metadata about the request including account and connection information
      type: object
      required:
      - options
      - data
      - metadata
      title: TransactionScanRequest
  securitySchemes:
    APIKey:
      type: apiKey
      name: X-API-Key
      in: header
    ClientID:
      type: apiKey
      name: X-CLIENT-ID
      in: header
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token. See [API Authentication](/docs/api-reference/before-you-begin/api-authentication) for how to retrieve it.