openapi: 3.0.3
info:
  title: Arkham Intel API
  version: 1.0.0
  license:
    name: Prop
    url: addurllater
  description: >
    **Arkham Intelligence official API documentation**


    The Arkham API provides direct query access to Ultra, our proprietary
    AI-powered algorithmic address matching engine, enabling sophisticated users
    to customize data flows and integrate them into their existing systems.


    Through the API, users can write custom queries to access a list of Arkham
    labels, as well as transaction logs and historical balance data for
    addresses and entities.


    Institutions that onboard to the **[Arkham Exchange](https://arkm.com)**
    automatically qualify for access to this API.


    The [deprecated API
    documentation](https://arkham-intelligence.notion.site/Arkham-API-Access-9232652274854efaa8a67633a94a2595)
    is available here in multiple languages; however, please note that it is no
    longer being updated.


    ---

    ## ⚠️ IMPORTANT: API-Key 


    **All API requests MUST include a valid `API-Key` header. Requests without
    this header will be rejected with an unauthorized response.**


    To authenticate with Arkham's API, simply provide a valid `API-Key` in the
    header of your request. To apply for API access to our platform, visit:
    [https://info.arkm.com/api-platform](https://info.arkm.com/api-platform).


    ## Endpoints


    Our root URL is `https://api.arkm.com`.


    ## Rate limits


    Our API uses tier-based rate limits with different limits for different
    endpoints:


    ### Standard Rate Limits

    For the Basic API tier, most endpoints allow up to 20 requests per second
    with a small additional burst allowance for occasional spikes beyond that
    threshold.


    ### Heavy Endpoints Rate Limits

    Some resource-intensive endpoints have lower rate limits of 1 request per
    second:

    - /transfers

    - /swaps

    - /counterparties/address/{address}

    - /counterparties/entity/{entity}

    - /token/top_flow/{id}

    - /token/top_flow/{chain}/{address}

    - /token/volume/{id}

    - /token/volume/{chain}/{address}

    - /transfers/histogram


    **Note**: These heavy endpoints are computationally intensive and query
    large amounts of data, hence the stricter rate limits to ensure platform
    stability.


    If you are consistently hitting the default rate limit we have set for our
    API you can apply for a rate limit increase
    [here](https://docs.google.com/forms/d/e/1FAIpQLSdUIXdQwfElz7JOdYGljIr0l9UybkY-uDhoFxJ4wzTDEV2zVw/viewform).


    ---

    ## Security and Privacy

    All data on our platform—including your private labels—is stored securely,
    using state-of-the-art encryption both at rest and in transit, along with
    strict access controls to ensure your information remains confidential. For
    further details on our security and privacy measures, please refer to our
    [Privacy Policy.](https://info.arkm.com/privacy-policy)
tags:
  - name: Health
    description: API Health check
  - name: Chains
    description: View full list of supported blockchains.
  - name: Transfers
    description: >-
      Provides endpoints for retrieving blockchain transfer and swap activity.
      These include detailed transfer lists, aggregated histograms for analyzing
      transfer trends over time, and DEX swap data, all filterable by various
      query parameters.
  - name: User entities
    description: >-
      Provides endpoints for managing custom entities created by an
      authenticated user. Entities can be retrieved in bulk or individually,
      with support for including associated blockchain addresses.
  - name: Entity bulk update
    description: >-
      Provides endpoints for updating custom entities in bulk. Entities can be
      fully overwritten (replacing details and address sets) or incrementally
      updated by adding new addresses without removing existing ones.
  - name: Transaction
    description: >-
      Provides an endpoint for retrieving detailed information about a specific
      blockchain transaction using its hash. The response includes metadata such
      as block number, timestamp, sender and recipient addresses, gas usage,
      fees, value in native units and USD, and token details.
  - name: ARKM
    description: >-
      Provides endpoints related to the ARKM token and Arkham Exchange tokens,
      including supply information and token listings.
  - name: Token exchange movements
    description: >-
      Provides an endpoint for analyzing token activity across centralized and
      decentralized exchanges. This includes ranking tokens by volume, inflows,
      outflows, netflows, and other metrics over customizable time intervals,
      with support for filtering by chain, market cap, and specific tokens.
  - name: Intelligence
    description: >-
      Provides AI-powered intelligence endpoints for analyzing blockchain
      addresses, entities, contracts, and tokens. These endpoints return
      enriched insights such as tagging data, entity associations, predicted
      addresses, contract metadata, and token information across multiple
      chains.
  - name: History
    description: >-
      Provides endpoints for retrieving historical analytics on blockchain
      entities and addresses. Returns time-series USD value snapshots to help
      analyze changes over time.
  - name: Portfolio
    description: >-
      Provides endpoints for managing and tracking entity and address
      portfolios. Includes historical snapshots, daily time-series data, and
      cross-chain portfolio analytics.
  - name: Token
    description: >-
      Provides endpoints for retrieving token-related information, including
      holders, flows, volumes, trending tokens, and balances across chains.
      These endpoints allow analysis of token distribution, trading activity,
      and ownership at both entity and address levels.
  - name: Market Data
    description: >-
      Provides an endpoint for accessing market data and analytics, including
      indices and metrics that track token and altcoin performance relative to
      the broader market.
  - name: Networks
    description: >-
      Provides endpoints for monitoring blockchain networks and retrieving
      chain-specific historical data, including current status and historical
      quotes.
  - name: Balances
    description: >-
      Provides endpoints for tracking and retrieving token balances for
      blockchain addresses and entities, with optional filtering by chain.
  - name: Loans
    description: >-
      Provides endpoints for tracking loan and borrow positions on-chain,
      including supplied, borrowed, and outstanding assets for addresses and
      entities.
  - name: Counterparties
    description: >-
      Provides endpoints for analyzing counterparty activity, aggregating top
      counterparties by volume for addresses and entities. Supports filtering by
      transfer direction, chain, token, time range, and transaction value.
  - name: Labels
    description: >-
      Provides endpoints for managing user-defined labels, including creating,
      retrieving, updating, and deleting labels associated with blockchain
      addresses.
  - name: Flow
    description: >-
      Provides endpoints for analyzing historical USD flows for addresses and
      entities across supported chains, including inflows, outflows, and running
      totals over time.
x-tagGroups:
  - name: ARKHAM API
    tags:
      - Health
      - Chains
      - Transfers
      - Transaction
      - Token exchange movements
      - User entities
      - Entity bulk update
      - Intelligence
      - History
      - Portfolio
      - Token
      - Market Data
      - ARKM
      - Networks
      - Balances
      - Loans
      - Counterparties
      - Labels
      - Flow
servers:
  - url: https://api.arkm.com
    description: Production server
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: API-Key
      description: API key for authentication
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Bad request
    Unauthorized:
      description: Unauthorized request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: API key missing or invalid
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Not found
    InternalServerError:
      description: Internal server error.
  schemas:
    Chain:
      type: string
      enum:
        - ethereum
        - polygon
        - bsc
        - optimism
        - avalanche
        - arbitrum_one
        - bitcoin
        - tron
        - base
        - flare
        - linea
        - manta
        - blast
        - ton
        - solana
        - mantle
        - dogecoin
        - sonic
      example: bitcoin
    ChainType:
      type: string
      enum:
        - evm
        - bitcoin
        - tron
        - ton
        - solana
        - dogecoin
      example: evm
    Label:
      type: object
      properties:
        name:
          type: string
          example: Bitoin Label
        note:
          type: string
          example: Label for Bitcoin address
        address:
          type: string
          example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
        chainType:
          $ref: '#/components/schemas/ChainType'
      required:
        - name
        - address
        - chainType
    LabelInput:
      type: object
      properties:
        name:
          type: string
          maxLength: 256
          example: Ethereum Label
        note:
          type: string
          maxLength: 1024
          example: Label for Ethereum address
        address:
          type: string
          example: '0xABCDEF1234567890'
        chainType:
          $ref: '#/components/schemas/ChainType'
      required:
        - name
        - address
        - chainType
    TopToken:
      type: object
      properties:
        token:
          type: object
          properties:
            id:
              type: string
              example: arkham
            symbol:
              type: string
              example: arkm
            marketCap:
              type: number
              example: 266713684.866522
              nullable: true
        current:
          $ref: '#/components/schemas/TopTokenInterval'
        previous:
          $ref: '#/components/schemas/TopTokenInterval'
    TopTokenInterval:
      type: object
      properties:
        price:
          type: number
          example: 0.579717
        inflowDexVolume:
          type: number
          example: 3954413.773988366
        inflowCexVolume:
          type: number
          example: 835149.3657948226
        outflowDexVolume:
          type: number
          example: 835232.8781155571
        outflowCexVolume:
          type: number
          example: 22801170.168555997
    EntityUpdateRequest:
      type: object
      required:
        - name
        - id
      properties:
        name:
          type: string
          example: Example Name
        note:
          type: string
          example: Updated note
        id:
          type: string
          example: exampleID
        type:
          type: string
          nullable: true
          example: null
        service:
          type: boolean
          nullable: true
          example: null
        addresses:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            evm:
              - '0xC17eF7e2689DFf7D269Ae2C22f857AcD60B42187'
              - '0x7dCC00d0Da47e6982672CB1C2481A6943737af45'
            bitcoin:
              - bc1qd7m42p9w8djak3qeme06stw7ach7hewa88rd6q0rgegw3mdlpl5s5wje56
            solana:
              - H6r6ShBfuoVYCCb8ZJANFYfR4y1EXr4vTLYPKbmHGxtv
            tron:
              - TLBsPRBS6WeB6DyzKSNhKXHxaWESeoK44g
        ownerUID:
          type: string
          example: exampleOwnerId
        linkShareable:
          type: boolean
          example: false
        createdAt:
          type: string
          format: date-time
          example: '2019-07-12T11:18:33Z'
        updatedAt:
          type: string
          format: date-time
          example: '2019-07-12T12:47:55Z'
    Entity:
      type: object
      properties:
        id:
          type: string
          example: vitalik-buterin
        name:
          type: string
          example: Vitalik Buterin
        note:
          type: string
          example: ''
        addresses:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          nullable: true
          example: null
        customized:
          type: boolean
          example: false
        type:
          type: string
          nullable: true
          example: individual
        service:
          type: boolean
          nullable: true
          example: null
        ownerUID:
          type: string
          nullable: true
          example: if0jX2ggQzRlZnKYieI6uhLb07W1
        website:
          type: string
          example: https://vitalik.eth.limo/
        twitter:
          type: string
          example: https://x.com/vitalikbuterin
        crunchbase:
          type: string
          example: https://www.crunchbase.com/person/vitalik-buterin
        linkedin:
          type: string
          example: https://ca.linkedin.com/in/vitalik-buterin-267a7450
        instagram:
          type: string
          example: https://www.instagram.com/vitalik.eth.official
        customImageSlug:
          type: string
          example: https://static.arkhamintelligence.com/entities/vitalik-buterin.png
        populatedTags:
          type: array
          items:
            $ref: '#/components/schemas/PopulatedTag'
        linkShareable:
          type: boolean
          example: true
    PopulatedTag:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          example: kol
        label:
          type: string
          example: Key Opinion Leader
        rank:
          type: integer
          example: 4
        excludeEntities:
          type: boolean
          example: false
        chain:
          $ref: '#/components/schemas/Chain'
        disablePage:
          type: boolean
          example: false
    UserEntity:
      allOf:
        - $ref: '#/components/schemas/Entity'
        - type: object
          properties:
            createdAt:
              type: string
              format: date-time
              example: '2019-07-12T11:18:33Z'
            updatedAt:
              type: string
              format: date-time
              example: '2019-07-12T12:47:55Z'
    ArkhamEntity:
      allOf:
        - $ref: '#/components/schemas/Entity'
    Address:
      type: object
      properties:
        address:
          type: string
          description: The raw address (hex for EVM chains, base58 for Bitcoin, etc.)
          example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
        chain:
          $ref: '#/components/schemas/Chain'
          description: The chain associated with the address
          example: arbitrum_one
        depositServiceID:
          type: string
          nullable: true
          example: null
        arkhamEntity:
          type: object
          nullable: true
          properties:
            name:
              type: string
              nullable: true
              example: Vitalik Buterin
            note:
              type: string
              nullable: true
              example: ''
            id:
              type: string
              nullable: true
              example: vitalik-buterin
            type:
              type: string
              nullable: true
              example: individual
            service:
              type: string
              nullable: true
              example: null
            addresses:
              type: string
              nullable: true
              example: null
            website:
              type: string
              nullable: true
              example: null
            twitter:
              type: string
              nullable: true
              example: https://twitter.com/VitalikButerin
            crunchbase:
              type: string
              nullable: true
              example: https://www.crunchbase.com/person/vitalik-buterin
            linkedin:
              type: string
              nullable: true
              example: https://www.linkedin.com/in/vitalik-buterin-267a7450
        arkhamLabel:
          type: object
          nullable: true
          properties:
            name:
              type: string
              nullable: true
              example: vitalik.eth
            address:
              type: string
              nullable: true
              example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
            chainType:
              $ref: '#/components/schemas/ChainType'
              nullable: true
              example: evm
        isUserAddress:
          type: boolean
          nullable: true
          example: false
        contract:
          type: boolean
          nullable: true
          example: false
      description: Blockchain address intelligence object
    AddressEnriched:
      allOf:
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            clusterIds:
              type: array
              items:
                type: string
              nullable: true
              description: >-
                Array of cluster IDs associated with this address (when
                includeClusters=true)
            populatedTags:
              type: array
              items:
                $ref: '#/components/schemas/PopulatedTag'
              nullable: true
              description: >-
                Populated tags associated with this address (when
                includeTags=true)
            predictedEntity:
              $ref: '#/components/schemas/Entity'
              nullable: true
              description: >-
                Predicted entity information for this address (when
                includeEntityPredictions=true)
      description: >
        Blockchain address intelligence object with optional enrichment fields.
        Fields like populatedTags, clusterIds, and predictedEntity are included
        based on query parameters.
    PortfolioEntry:
      type: object
      properties:
        id:
          type: string
          example: ethereum
        name:
          type: string
          example: Ethereum
        symbol:
          type: string
          example: eth
        balance:
          type: number
          example: 4.78807409176358
        price:
          type: number
          example: 4274.81
        usd:
          type: number
          example: 20468.10700821187
    AddressPortfolioHistory:
      type: object
      description: >
        A map where each key is a chain name and the value is a map of portfolio
        entries keyed by asset ID.
      additionalProperties:
        type: object
        additionalProperties:
          $ref: '#/components/schemas/PortfolioEntry'
      example:
        arbitrum_one:
          ethereum:
            id: ethereum
            name: Ethereum
            symbol: eth
            balance: 0.056655439986338416
            price: 4274.81
            usd: 242.19124140799934
          usd_coin:
            id: usd-coin
            name: USDC
            symbol: usdc
            balance: 66.322642
            price: 0.999806
            usd: 66.309775407452
        ethereum:
          ethereum:
            id: ethereum
            name: Ethereum
            symbol: eth
            balance: 4.78807409176358
            price: 4274.81
            usd: 20468.10700821187
          usd_coin:
            id: usd-coin
            name: USDC
            symbol: usdc
            balance: 19094.757669000097
            price: 0.999806
            usd: 19091.05328601231
    EntityPortfolioHistory:
      type: object
      description: >-
        A map where each key is a chain name and the value is a map of portfolio
        entries keyed by asset ID.
      additionalProperties:
        type: object
        additionalProperties:
          $ref: '#/components/schemas/PortfolioEntry'
      example:
        arbitrum_one:
          ethereum:
            id: ethereum
            name: Ethereum
            symbol: eth
            balance: 0.056655439986338416
            price: 4274.81
            usd: 242.19124140799934
          usd_coin:
            id: usd-coin
            name: USDC
            symbol: usdc
            balance: 66.322642
            price: 0.999806
            usd: 66.309775407452
        ethereum:
          ethereum:
            id: ethereum
            name: Ethereum
            symbol: eth
            balance: 4.78807409176358
            price: 4274.81
            usd: 20468.10700821187
          usd_coin:
            id: usd-coin
            name: USDC
            symbol: usdc
            balance: 19094.757669000097
            price: 0.999806
            usd: 19091.05328601231
    Transfer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier (transaction hash + log index)
          example: '0xded143b3e5dd3c9f6987783d0f0f2af1cec746553113a015a23f1213038b3972'
        transactionHash:
          type: string
          example: '0xded143b3e5dd3c9f6987783d0f0f2af1cec746553113a015a23f1213038b3972'
        fromAddress:
          $ref: '#/components/schemas/Address'
        toAddress:
          $ref: '#/components/schemas/Address'
        tokenAddress:
          type: string
          nullable: true
          example: null
        type:
          type: string
          description: external, internal, or token
          example: ''
        blockTimestamp:
          type: string
          format: date-time
          example: '2025-06-04T09:07:47Z'
        blockNumber:
          type: integer
          nullable: true
          example: 22630280
        blockHash:
          type: string
          nullable: true
          example: '0xb73b329bad7428bdace6623dcd18743fca05b136116c261b63224176d831d997'
        tokenName:
          type: string
          nullable: true
          example: Ethereum
        tokenSymbol:
          type: string
          nullable: true
          example: ETH
        tokenDecimals:
          type: integer
          nullable: true
          example: 18
        unitValue:
          type: number
          nullable: true
          example: 259.6
        tokenId:
          type: string
          nullable: true
          example: ethereum
        historicalUSD:
          type: number
          nullable: true
          example: 685673.692
        chain:
          $ref: '#/components/schemas/Chain'
          description: The chain on which the transfer occurred
          example: ethereum
    Swap:
      type: object
      properties:
        id:
          type: string
          example: >-
            0x1aa3b159d3a20326daf41fee27225fd4229d0428179513bbbd2fc1aa469c041b_327
        chain:
          $ref: '#/components/schemas/Chain'
          example: ethereum
        blockTimestamp:
          type: string
          format: date-time
          example: '2021-10-22T17:26:37Z'
        blockNumber:
          type: integer
          example: 13468727
        blockHash:
          type: string
          example: '0x6aa90482faf144b3f66e4ee569cc64958660ef40cdec239c363d3d4de7c56cc8'
        contractAddress:
          $ref: '#/components/schemas/Address'
        sender:
          $ref: '#/components/schemas/Address'
        receiver:
          $ref: '#/components/schemas/Address'
        unitValue0:
          type: number
          nullable: true
          example: 117299080646369.72
        unitValue1:
          type: number
          nullable: true
          example: -145.2145781084285
        historicalUSD:
          type: number
          nullable: true
          example: 2370363.5776504306
        token0:
          type: string
          nullable: true
          example: '0x97b65710D03E12775189F0D113202cc1443b0aa2'
        token0Id:
          type: string
          nullable: true
          example: weth
        token0Name:
          type: string
          nullable: true
          example: ASTROELON
        token0Symbol:
          type: string
          nullable: true
          example: ELONONE
        token0Decimals:
          type: integer
          nullable: true
          example: 9
        token1:
          type: string
          nullable: true
          example: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
        token1Id:
          type: string
          nullable: true
          example: weth
        token1Name:
          type: string
          nullable: true
          example: Wrapped Ether
        token1Symbol:
          type: string
          nullable: true
          example: WETH
        token1Decimals:
          type: integer
          nullable: true
          example: 18
        valid:
          type: boolean
          nullable: true
          example: true
        contractEntityId:
          type: string
          nullable: true
          example: uniswap
      description: Data for a single swap event
    HistogramItem:
      type: object
      properties:
        time:
          type: string
          format: date-time
          example: '2025-03-31T00:00:00Z'
        count:
          type: integer
          example: 17
        usd:
          type: number
          example: 983
      description: Aggregated transaction data for a time bucket
    Contract:
      type: object
      properties:
        address:
          type: string
          example: '0x882df4B0fB50a229C3B4124EB18c759911485bFb'
        bytecode:
          type: string
          nullable: true
          example: ''
        functionSighashes:
          type: array
          nullable: true
          items:
            type: string
          example: null
        isProxy:
          type: boolean
          nullable: true
          example: false
        proxyAddress:
          type: string
          nullable: true
          example: null
        blockTimestamp:
          type: string
          format: date-time
          nullable: true
          example: '2024-03-06T16:34:32Z'
        deployer:
          $ref: '#/components/schemas/Address'
        internalDeployer:
          $ref: '#/components/schemas/Address'
      description: Contract intelligence data
    TokenBasicInfo:
      type: object
      properties:
        identifier:
          type: object
          properties:
            pricingID:
              type: string
              example: bitcoin
        name:
          type: string
          example: Bitcoin
        symbol:
          type: string
          example: btc
        tvTicker:
          type: string
          nullable: true
          example: BINANCE:BTCUSDT
      description: Basic token intelligence data
    NetworkStatus:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        active:
          type: boolean
          example: true
        price:
          type: number
          example: 113823
        priceChange24h:
          type: number
          example: -1623
        priceChange24hPercent:
          type: number
          example: -1.405852086689881
        volume:
          type: number
          example: 45315548103
        marketCap:
          type: number
          example: 2266226246486
        tip:
          type: integer
          example: 910860
        tps:
          type: number
          example: 0
        transfers:
          type: integer
          example: 3437478521
        gasFee:
          type: number
          nullable: true
          example: null
        satFee:
          type: integer
          nullable: true
          example: 1550
      description: Basic status information for a given network
    TokenHistoricalQuote:
      type: object
      properties:
        time:
          type: string
          format: date-time
          example: '2025-08-18T16:34:32Z'
        usd:
          type: number
          example: 113823
        volume24h:
          type: number
          nullable: true
          example: 45315548103
        marketCap:
          type: number
          nullable: true
          example: 2266226246486
      description: Historical quote/time-series entry for a network or token
    TrendingToken:
      type: object
      properties:
        name:
          type: string
          nullable: true
          example: Solana
        symbol:
          type: string
          nullable: true
          example: sol
        pricingID:
          type: string
          example: solana
        price:
          type: number
          example: 181.66
        price24hAgo:
          type: number
          example: 181.86
        volume24h:
          type: number
          example: 5669421323
        allTimeHigh:
          type: number
          example: 293.31
        allTimeLow:
          type: number
          example: 0.500801
        circulatingSupply:
          type: number
          nullable: true
          example: 540069217.3525627
      description: A trending token data object
    TxDetail:
      type: object
      additionalProperties:
        type: object
        properties:
          hash:
            type: string
            example: '0x0eca8c072b46f1ba1e6b5cb9f686614e7052c66f798dab594fed7e747abc1bcc'
          blockTimestamp:
            type: string
            format: date-time
            example: '2025-08-20T10:56:33Z'
          fromAddress:
            type: string
            example: '0xAcFf6D7B46567D5334150bB69584C1881e31b6bA'
          toAddress:
            type: string
            nullable: true
            example: '0x9a0b6082f3b0DBF711C18dF0db6901B9cDbf04cb'
          contractAddress:
            type: string
            nullable: true
            example: null
          unitValue:
            type: number
            nullable: true
            example: 0
          usdValue:
            type: number
            nullable: true
            example: 0
          gasUsageByTransaction:
            type: number
            nullable: true
            example: 149320
          gasLimit:
            type: number
            nullable: true
            example: 15000000
          gasPrice:
            type: number
            nullable: true
            example: 0.1
          fee:
            type: number
            nullable: true
            example: 0.000014932
          blockNumber:
            type: integer
            nullable: true
            example: 58252301
          receiptStatus:
            type: integer
            nullable: true
            example: 1
          ethPrice:
            type: number
            nullable: true
            example: 831.9
          tokenID:
            type: string
            nullable: true
            example: binancecoin
          tokenSymbol:
            type: string
            nullable: true
            example: BNB
          chain:
            $ref: '#/components/schemas/Chain'
            nullable: true
            example: bsc
    Counterparty:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        usd:
          type: number
          nullable: true
          example: 9198.798828125
        transactionCount:
          type: integer
          nullable: true
          example: 4
        flow:
          type: string
          enum:
            - in
            - out
            - all
          nullable: true
          example: in
        chains:
          type: array
          items:
            $ref: '#/components/schemas/Chain'
      description: A counterparty aggregated info
    LoanPosition:
      type: object
      properties:
        name:
          type: string
          example: Aave Ethereum WETH
        symbol:
          type: string
          example: aEthWETH
        id:
          type: string
          example: aave-v3-weth
        address:
          type: string
          nullable: true
          example: '0x4d5F47FA6A74757f35C14fD3a6Ef8E3C9BC514E8'
        balance:
          type: number
          nullable: true
          example: 2906.1865642461335
        usd:
          type: number
          nullable: true
          example: 12484628.73761368
        price:
          type: number
          nullable: true
          example: 4295.88
        protocol:
          type: string
          nullable: true
          example: AAVE_V3
        type:
          type: string
          enum:
            - yield
            - supplied
            - borrowed
          nullable: true
          example: supplied
      description: A single loan/borrowed-lent position item
    BalanceDetail:
      type: object
      properties:
        name:
          type: string
          example: Aave Ethereum WETH
        symbol:
          type: string
          example: aEthWETH
        id:
          type: string
          example: aave-v3-weth
        ethereumAddress:
          type: string
          nullable: true
          example: '0x4d5F47FA6A74757f35C14fD3a6Ef8E3C9BC514E8'
        balance:
          type: number
          nullable: true
          example: 2906.1865642461335
        balanceExact:
          type: string
          nullable: true
          example: '0'
        usd:
          type: number
          nullable: true
          example: 12526303.45294497
        price:
          type: number
          nullable: true
          example: 4310.22
        quoteTime:
          type: string
          format: date-time
          nullable: true
          example: '2025-08-21T08:35:06.027Z'
        priceChange24hPercent:
          type: number
          nullable: true
          example: 1.7766317668560583
        priceChange24h:
          type: number
          nullable: true
          example: 75.24000000000069
      description: A single token balance detail item
    TagSummary:
      type: object
      properties:
        tagId:
          type: string
          description: The tag identifier
          example: individual
        numAddresses:
          type: integer
          format: int64
          description: Total number of unique addresses with this tag
          example: 17500202
        numEntities:
          type: integer
          format: int64
          description: Total number of entities with this tag
          example: 546104
        numUniqueTagParams:
          type: integer
          format: int64
          description: Number of unique tag parameter variations
          example: 0
      description: Precomputed summary statistics for tags
    ClusterSummary:
      type: object
      properties:
        clusterId:
          type: string
          description: The cluster identifier
          example: 29d502f1236dd5563fbb7799f30b39d80400555674757acb7869055cebdfc6da
        numAddresses:
          type: integer
          format: int64
          description: Total number of unique addresses in this cluster
          example: 1523
        volumeUsd:
          type: number
          format: double
          description: Total transaction volume in USD
          example: 125000000.5
        balanceUsd:
          type: number
          format: double
          description: Current balance in USD
          example: 85000000.25
        firstTx:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of first transaction
          example: '2017-07-14T10:02:13Z'
        lastTx:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of last transaction
          example: '2025-10-29T14:23:45Z'
      description: Summary statistics for a cluster
    EntitySummary:
      type: object
      properties:
        entityId:
          type: string
          description: The entity identifier
          example: xyz-exchange
        numAddresses:
          type: integer
          format: int64
          description: >-
            Total number of unique addresses for this entity (deduplicated
            across chains)
          example: 1523
        volumeUsd:
          type: number
          format: double
          description: Total transaction volume in USD across all chains
          example: 125000000.5
        balanceUsd:
          type: number
          format: double
          description: Current balance in USD across all chains
          example: 85000000.25
        firstTx:
          type: string
          format: date-time
          nullable: true
          description: >-
            Timestamp of first transaction across all chains (null if no
            transactions)
          example: '2017-07-14T10:02:13Z'
        lastTx:
          type: string
          format: date-time
          nullable: true
          description: >-
            Timestamp of last transaction across all chains (null if no
            transactions)
          example: '2025-10-29T14:23:45Z'
      description: Summary statistics for an entity
    TopFlowItem:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        inUSD:
          type: number
          nullable: true
          example: 8337419.937040014
        outUSD:
          type: number
          nullable: true
          example: 8300701.09322816
        inValue:
          type: number
          nullable: true
          example: 1941.1915603221187
        outValue:
          type: number
          nullable: true
          example: 1932.6267573327154
    TokenVolumeItem:
      type: object
      properties:
        inUSD:
          type: number
          nullable: true
          example: 78885.30107270926
        outUSD:
          type: number
          nullable: true
          example: 35819.741134643555
        inValue:
          type: number
          nullable: true
          example: 18.680140332941466
        outValue:
          type: number
          nullable: true
          example: 8.482160776528666
        time:
          type: string
          format: date-time
          nullable: true
          example: '2025-08-20T09:00:00Z'
    TokenBalanceItem:
      type: object
      properties:
        pricingID:
          type: string
          example: ethereuem
        name:
          type: string
          example: Ethereum
        symbol:
          type: string
          example: ETH
        balance:
          type: number
          nullable: true
          example: 4559842.890596902
        price:
          type: number
          nullable: true
          example: 4268.59
        usd:
          type: number
          nullable: true
          example: 19464099764.373035
      description: Token balance for an entity or address
    FlowSnapshot:
      type: object
      properties:
        time:
          type: string
          format: date-time
          description: The timestamp for this flow snapshot
          example: '2017-10-02T00:00:00Z'
        inflow:
          type: number
          description: USD value flowing into the address/entity during this time period
          example: 6755190.46
        outflow:
          type: number
          description: USD value flowing out of the address/entity during this time period
          example: 6396218.99
        cumulativeInflow:
          type: number
          description: Running total of USD inflows up to this time
          example: 254934139.7900001
        cumulativeOutflow:
          type: number
          description: Running total of USD outflows up to this time
          example: 250976886.60000002
      description: Snapshot of flow data for a given time period
    EntityPrediction:
      type: object
      properties:
        address:
          type: string
          description: The blockchain address
          example: '0xebDce3B3775c5683c96Ca754e4130Ea5175De85E'
        entityID:
          type: string
          description: The predicted entity ID for this address
          example: binance
        usdBalance:
          type: number
          description: The approx USD balance for this address
          example: 1337879888.38
      description: Entity prediction object
security:
  - ApiKeyAuth: []
paths:
  /health:
    get:
      operationId: getHealth
      tags:
        - Health
      summary: Health check endpoint
      description: Returns a simple "ok" text if the server is running.
      responses:
        '200':
          description: Health check successful
          content:
            text/plain:
              schema:
                type: string
                example: ok
        '500':
          $ref: '#/components/responses/InternalServerError'
  /chains:
    get:
      operationId: getChains
      tags:
        - Chains
      summary: Get supported chains list
      description: >
        Retrieves a list of supported blockchain chains. The response is a
        simple JSON array of chain identifiers.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful retrieval of the chains list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
                - ethereum
                - bitcoin
                - solana
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transfers:
    get:
      operationId: getTransfers
      tags:
        - Transfers
      summary: Get transfers
      description: >
        Retrieves a list of transfers based on various query filters.


        **Rate Limit**: This endpoint has a stricter rate limit of 1 request per
        second.


        **Filter parameters:**

        - **base**: Filter by specific entity or address. For example,
        "0x123abc" or "binance".

        - **chains**: Specify a comma-separated list of chains (e.g.
        "ethereum,bsc").

        - **flow**: Direction of the transfer. Valid values are "in" (incoming),
        "out" (outgoing), "self" (self-transfers), or "all".

        - **from**: Comma-separated list of addresses, entities, or deposit
        services for the 'from' side of a transfer. You can also use special
        syntax like `"type:cex"` to filter on entity types or
        `"deposit:binance"` to filter on deposit addresses.

        - **to**: Comma-separated list of addresses, entities, or deposit
        services for the 'to' side.

        - **tokens**: Comma-separated list of token addresses or token IDs. E.g.
        "ethereum", "usd-coin", or "0x...tokenAddress".

        - **counterparties**: Comma-separated list of addresses or entities to
        treat strictly as counterparties (only base <-> counterparty transfers).

        - **timeLast**: Filter transfers from a recent duration. For example,
        "24h" returns transfers from the last 24 hours.

        - **timeGte/timeLte**: Filter from/to a specific timestamp in
        milliseconds.

        - **valueGte/valueLte**: Numeric filters on the raw token amount
        (on-chain units).

        - **usdGte/usdLte**: Numeric filters on the historical USD value of the
        transfer.

        - **sortKey**: Field by which to sort the results. Options include
        "time", "value", or "usd".

        - **sortDir**: Sorting direction. Use "asc" for ascending or "desc" for
        descending.

        - **limit**: Maximum number of results to return (default is 50).

        - **offset**: Pagination offset (default is 0).
      security:
        - ApiKeyAuth: []
      parameters:
        - name: base
          in: query
          schema:
            type: string
          description: >
            Filter by specific entity or address. For example: "0x123abc" or
            "binance".
        - name: chains
          in: query
          schema:
            type: string
          description: |
            Comma-separated list of chains. For example: "ethereum,bsc".
        - name: flow
          in: query
          schema:
            type: string
            enum:
              - in
              - out
              - self
              - all
          description: >
            Transfer direction: "in" for incoming, "out" for outgoing, "self"
            for self-transfers, or "all" for all transfers.
        - name: from
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of addresses, entities, or deposit services for
            the 'from' side. You can also use special syntax like `"type:cex"`
            to filter on entity types or `"deposit:binance"` to filter on
            deposit addresses.
        - name: to
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of addresses, entities, or deposit services for
            the 'to' side.
        - name: tokens
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of token addresses or token IDs. E.g.
            "ethereum", "usd-coin", or "0x...tokenAddress".
        - name: counterparties
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of addresses or entities to treat strictly as
            counterparties (only base <-> counterparty transfers).
        - name: timeLast
          in: query
          schema:
            type: string
          description: >
            Time range filter using relative durations. For example: "24h" for
            transfers in the last 24 hours, "7d" for last 7 days.
        - name: timeGte
          in: query
          schema:
            type: string
          description: |
            Time range filter (from) in milliseconds (e.g. `1696630274000`).
        - name: timeLte
          in: query
          schema:
            type: string
          description: |
            Time range filter (to) in milliseconds (e.g. `1696716674000`).
        - name: valueGte
          in: query
          schema:
            type: number
          description: |
            Minimum raw token value (on-chain units).
        - name: valueLte
          in: query
          schema:
            type: number
          description: |
            Maximum raw token value (on-chain units).
        - name: usdGte
          in: query
          schema:
            type: number
          description: |
            Minimum historical USD value.
        - name: usdLte
          in: query
          schema:
            type: number
          description: |
            Maximum historical USD value.
        - name: sortKey
          in: query
          schema:
            type: string
            enum:
              - time
              - value
              - usd
        - name: sortDir
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
          description: |
            Maximum number of results to return.
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: |
            Pagination offset.
      responses:
        '200':
          description: Successful list of transfers
          content:
            application/json:
              schema:
                type: object
                properties:
                  transfers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transfer'
                  count:
                    type: integer
                    example: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /ws/transfers:
    get:
      tags:
        - Transfers
      summary: WebSocket Transfer Streaming
      operationId: getWebSocketTransfers
      x-hideReplay: true
      description: >
        WebSocket endpoint for streaming real-time blockchain transfers. Connect
        to `wss://api.arkm.com/ws/transfers` with API-Key header..


        **Authentication:** Include your API-Key as a header during the
        WebSocket connection handshake.


        **Client Messages:**

        - **subscribe** - Create a new filter to receive matching transfers
          ```json
          {
            "id": "1",
            "type": "subscribe",
            "payload": {
              "filters": {
                "from": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
                "to": ["binance", "coinbase"],
                "chains": ["ethereum"],
                "tokens": ["USDT"],
                "usdGte": 100000
              }
            }
          }
          ```

        - **unsubscribe** - Remove an existing filter by ID
          ```json
          {
            "id": "2",
            "type": "unsubscribe",
            "payload": {
              "filterId": 123
            }
          }
          ```

        - **reconnect** - Restore a previous session within 5 minutes of
        disconnection
          ```json
          {
            "id": "3",
            "type": "reconnect",
            "payload": {
              "sessionId": "ws_abc_123"
            }
          }
          ```

        **Server Messages:**

        - **transfer** - Real-time transfer notification matching your filters
          Example:
          ```json
          {
            "type": "transfer",
            "payload": {
              "transfer": {
                "id": "0xc99175260fd56ae461c7dce8d5f79e8aee068225ac5237932594880b277a87d1_502",
                "transactionHash": "0xc99175260fd56ae461c7dce8d5f79e8aee068225ac5237932594880b277a87d1",
                "fromAddress": {
                  "address": "0x28C6c06298d514Db089934071355E5743bf21d60",
                  "chain": "ethereum",
                  "arkhamEntity": {
                    "name": "Binance",
                    "note": "",
                    "id": "binance",
                    "type": "cex",
                    "service": null,
                    "addresses": null,
                    "website": "https://binance.com",
                    "twitter": "https://twitter.com/binance",
                    "crunchbase": "https://www.crunchbase.com/organization/binance",
                    "linkedin": "https://www.linkedin.com/company/binance"
                  },
                  "arkhamLabel": {
                    "name": "Hot Wallet",
                    "address": "0x28C6c06298d514Db089934071355E5743bf21d60",
                    "chainType": "evm"
                  },
                  "isUserAddress": false,
                  "contract": false
                },
                "fromIsContract": false,
                "toAddress": {
                  "address": "0x401a39874f38a254a192bf58Dc52eD2A5078535D",
                  "chain": "ethereum",
                  "isUserAddress": false,
                  "contract": false
                },
                "toIsContract": false,
                "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
                "type": "token",
                "blockTimestamp": "2025-08-28T11:01:35Z",
                "blockNumber": 23239187,
                "blockHash": "0xb75f0e8d59bd5f1a72d4ba54e3576a750580735b3c1bf34a9fbd73b2251c963e",
                "tokenName": "Tether USD",
                "tokenSymbol": "USDT",
                "tokenDecimals": 6,
                "unitValue": 503.9,
                "tokenId": "tether",
                "historicalUSD": 503.9,
                "chain": "ethereum"
              },
              "alertId": 49
            }
          }
          ```

        - **ack** - Acknowledgment for successful operations
          Example (subscribe success):
          ```json
          {
            "type": "ack",
            "payload": {
              "messageId": "1",
              "success": true,
              "message": "Filter created successfully",
              "data": {
                "filterId": 49,
                "sessionId": "ws_ad5c5dbb_1756378801"
              }
            }
          }
          ```

        - **error** - Error notifications for various failure scenarios
          Example (rate limited):
          ```json
          {
            "type": "error",
            "payload": {
              "code": "TIER_RATE_LIMITED",
              "limitType": "minutely",
              "message": "You have reached your per-minute WebSocket notification limit. Limit resets in 45 seconds.",
              "resetIn": 45
            }
          }
          ```

        **Rate Limits:**

        - 10,000 transfers per hour

        - 1,000,000 transfers per month

        - 1 API credit consumed per transfer sent


        **Filter Requirements:**

        - Must include at least one of: from, to, tokens, base, or usdGte >=
        10,000,000

        - Initial transfers may take up to 90 seconds after subscribing
      servers:
        - url: wss://api.arkm.com
          description: WebSocket server
      security:
        - ApiKeyAuth: []
      responses:
        '101':
          description: WebSocket connection upgrade successful
        '400':
          description: Invalid WebSocket upgrade request
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transfers/histogram/simple:
    get:
      operationId: getTransfersHistogramSimple
      tags:
        - Transfers
      summary: Get a simple histogram of transfers (Public)
      description: >
        Returns a simplified aggregated histogram of transfers over time. This
        is a public endpoint with basic rate limiting.


        **Note**: For the full-featured histogram endpoint with all filter
        options, use `/transfers/histogram` which requires API authentication.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: base
          in: query
          schema:
            type: string
          description: Filter by specific entity or address
        - name: chains
          in: query
          schema:
            type: string
          description: Comma-separated list of chains
        - name: flow
          in: query
          schema:
            type: string
            enum:
              - in
              - out
              - self
              - all
          description: Transfer direction
        - name: timeLast
          in: query
          schema:
            type: string
          description: Time range filter (e.g. "24h", "7d")
        - name: timeGte
          in: query
          schema:
            type: string
          description: Start time in milliseconds
        - name: timeLte
          in: query
          schema:
            type: string
          description: End time in milliseconds
      responses:
        '200':
          description: Successful histogram data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistogramItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /transfers/histogram:
    get:
      operationId: getTransfersHistogram
      tags:
        - Transfers
      summary: Get a detailed histogram of transfers (API Only)
      description: >
        Returns an aggregated histogram of transfers over time (count and USD
        values) based on the same filter parameters used in `/transfers`.


        **⚠️ This endpoint requires API tier authentication (not just API key)**


        **Rate Limit**: This endpoint has a stricter rate limit of 1 request per
        second.


        **Additional parameter**:

        - **granularity**: "1h" or "1d" (if the range exceeds 30 days, "1h" is
        invalid).


        **Filter parameters** (same as `/transfers`, minus pagination/sorting):

        - **base**: Filter by specific entity or address. For example,
        "0x123abc" or "binance".

        - **chains**: Specify a comma-separated list of chains (e.g.
        "ethereum,bsc").

        - **flow**: Direction of the transfer. Valid values are "in", "out",
        "self", or "all".

        - **timeLast**: Filter from a recent duration (e.g. "24h", "7d", "30d",
        etc.).

        - **timeGte/timeLte**: Filter from/to a specific timestamp in
        milliseconds.

        - **valueGte/valueLte**: Numeric filters on the raw token amount.

        - **usdGte/usdLte**: Numeric filters on the historical USD value of the
        transfer.

        - **from**: Comma-separated list of addresses, entities, or deposit
        services for the 'from' side.

        - **to**: Comma-separated list of addresses, entities, or deposit
        services for the 'to' side.

        - **tokens**: Comma-separated list of token addresses or token IDs.
          E.g. "ethereum", "usd-coin", or "0x...tokenAddress".
        - **counterparties**: Comma-separated list of addresses or entities to
        treat strictly as counterparties
          (only base <-> counterparty transfers).
      security:
        - ApiKeyAuth: []
      parameters:
        - name: base
          in: query
          required: false
          schema:
            type: string
          description: >
            Filter by specific entity or address. For example: "0x123abc" or
            "binance".
        - name: granularity
          in: query
          required: true
          schema:
            type: string
            enum:
              - 1h
              - 1d
          description: >
            Granularity of histogram buckets. Valid values: "1h" or "1d". For
            time ranges over 30 days, only "1d" is valid.
        - name: chains
          in: query
          schema:
            type: string
          description: |
            Comma-separated list of chains. For example: "ethereum,bsc".
        - name: flow
          in: query
          schema:
            type: string
            enum:
              - in
              - out
              - self
              - all
          description: >
            Transfer direction: "in" for incoming, "out" for outgoing, "self"
            for self-transfers, or "all".
        - name: timeLast
          in: query
          schema:
            type: string
          description: >
            Time range filter using relative durations. Examples: "24h", "7d",
            "30d".
        - name: timeGte
          in: query
          schema:
            type: string
          description: |
            Time range filter (from) in milliseconds (e.g. `1696630274000`).
        - name: timeLte
          in: query
          schema:
            type: string
          description: |
            Time range filter (to) in milliseconds (e.g. `1696716674000`).
        - name: valueGte
          in: query
          schema:
            type: number
          description: |
            Minimum raw token value (on-chain units).
        - name: valueLte
          in: query
          schema:
            type: number
          description: |
            Maximum raw token value (on-chain units).
        - name: usdGte
          in: query
          schema:
            type: number
          description: |
            Minimum historical USD value.
        - name: usdLte
          in: query
          schema:
            type: number
          description: |
            Maximum historical USD value.
        - name: from
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of addresses, entities, or deposit services for
            the 'from' side. You can also use special syntax like
            `"type:smart_money"` or `"deposit:binance"`.
        - name: to
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of addresses, entities, or deposit services for
            the 'to' side.
        - name: tokens
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of token addresses or token IDs. E.g.
            "ethereum", "usd-coin", or "0x...tokenAddress".
        - name: counterparties
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of addresses or entities to treat strictly as
            counterparties (only base <-> counterparty transfers).
      responses:
        '200':
          description: Successful histogram data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistogramItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /swaps:
    get:
      operationId: getSwaps
      tags:
        - Transfers
      summary: Get swaps
      description: >
        Retrieves a list of swaps (DEX trades) based on various query filters.


        **Rate Limit**: This endpoint has a stricter rate limit of 1 request per
        second.


        **Filter parameters:**

        - **base**: Filter by specific entity or address involved in the swap.

        - **chains**: Specify a comma-separated list of chains (e.g.
        "ethereum,bsc").

        - **flow**: Direction of the swap relative to base address. Valid values
        are "in" (receiving token1), "out" (sending token0), or "all".

        - **from**: Filter by sender addresses or entities.

        - **to**: Filter by receiver addresses or entities.

        - **tokens**: Comma-separated list of token addresses or token IDs that
        appear in either token0 or token1.

        - **timeLast**: Filter swaps from a recent duration (e.g. "24h", "7d").

        - **timeGte/timeLte**: Filter from/to a specific timestamp in
        milliseconds.

        - **usdGte/usdLte**: Numeric filters on the historical USD value of the
        swap.

        - **sortKey**: Field by which to sort the results. Options include
        "time" or "usd".

        - **sortDir**: Sorting direction. Use "asc" for ascending or "desc" for
        descending.

        - **limit**: Maximum number of results to return (default is 50).

        - **offset**: Pagination offset (default is 0).
      security:
        - ApiKeyAuth: []
      parameters:
        - name: base
          in: query
          schema:
            type: string
          description: Filter by specific entity or address
        - name: chains
          in: query
          schema:
            type: string
          description: Comma-separated list of chains
        - name: flow
          in: query
          schema:
            type: string
            enum:
              - in
              - out
              - all
          description: Swap direction relative to base address
        - name: from
          in: query
          schema:
            type: string
          description: Filter by sender addresses or entities
        - name: to
          in: query
          schema:
            type: string
          description: Filter by receiver addresses or entities
        - name: tokens
          in: query
          schema:
            type: string
          description: Comma-separated list of token addresses or IDs
        - name: timeLast
          in: query
          schema:
            type: string
          description: Time range filter (e.g. "24h", "7d")
        - name: timeGte
          in: query
          schema:
            type: string
          description: Start time in milliseconds
        - name: timeLte
          in: query
          schema:
            type: string
          description: End time in milliseconds
        - name: usdGte
          in: query
          schema:
            type: number
          description: Minimum historical USD value
        - name: usdLte
          in: query
          schema:
            type: number
          description: Maximum historical USD value
        - name: sortKey
          in: query
          schema:
            type: string
            enum:
              - time
              - usd
          description: Field to sort by
        - name: sortDir
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort direction
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Pagination offset
      responses:
        '200':
          description: List of swaps matching the filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  swaps:
                    type: array
                    items:
                      $ref: '#/components/schemas/Swap'
                  count:
                    type: integer
                    example: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/entities:
    get:
      operationId: getUserEntities
      tags:
        - User entities
      summary: Get all custom entities for authenticated user
      description: >
        Returns all custom entities owned by the authenticated user. This
        endpoint supports an optional parameter `includeAddresses` to control
        whether addresses are included in the response.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: includeAddresses
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: |
            Whether to include addresses for the custom entity in the response.
            - `true` (default): Returns entities with full address mappings
            - `false`: Returns entity metadata only (faster performance)
      responses:
        '200':
          description: >-
            Array of user entities with optional addresses based on
            includeAddresses parameter
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: '#/components/schemas/UserEntity'
                    - $ref: '#/components/schemas/ArkhamEntity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /user/entities/{id}:
    get:
      operationId: getUserEntityById
      tags:
        - User entities
      summary: Get individual custom entity by ID
      description: >
        Returns a single custom entity owned by the authenticated user,
        including all addresses for that entity.

        This endpoint always includes the full entity data with addresses.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the entity to retrieve
      responses:
        '200':
          description: Individual entity with full address data
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UserEntity'
                  - $ref: '#/components/schemas/ArkhamEntity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: updateUserEntity
      tags:
        - Entity bulk update
      summary: Overwrite an entity (replace addresses)
      description: >
        Updates an entity by overwriting its details and full address set. The
        complete JSON input must include the updated entity fields plus a
        multi‑chain `addresses` mapping. The `addresses` object is keyed by
        blockchain type (for example, `evm`, `bitcoin`, `solana`, etc.) and each
        value is an array of address strings.


        **Important:** Any existing addresses not present in the payload will be
        removed. Use `/user/entities/only_add/{id}` if you want to keep existing
        addresses and only append new ones.


        **Example Input Explanation:**

        - **name / note:** Optional text fields. `name` is limited to 256
        characters; `note` to 1024 characters.

        - **addresses:** Map of chain to array of addresses.

        - **Bulk updates allow up to 100 total addresses per entity. Ensure
        addresses are valid and formatted correctly.**
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >-
            Unique identifier of the entity to update. You can grab it from your
            url `https://intel.arkm.com/explorer/entity/{entityId}`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityUpdateRequest'
            example:
              id: exampleID
              name: Example Entity
              note: Updated note for my entity.
              addresses:
                evm:
                  - '0xC17eF7e2689DFf7D269Ae2C22f857AcD60B42187'
                  - '0x7dCC00d0Da47e6982672CB1C2481A6943737af45'
                bitcoin:
                  - >-
                    bc1qd7m42p9w8djak3qeme06stw7ach7hewa88rd6q0rgegw3mdlpl5s5wje56
                solana:
                  - H6r6ShBfuoVYCCb8ZJANFYfR4y1EXr4vTLYPKbmHGxtv
                tron:
                  - TLBsPRBS6WeB6DyzKSNhKXHxaWESeoK44g
      responses:
        '200':
          description: Successful update of the entity. Returns the updated entity.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UserEntity'
                  - $ref: '#/components/schemas/ArkhamEntity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /user/entities/only_add/{id}:
    put:
      operationId: updateUserEntityOnlyAdd
      tags:
        - Entity bulk update
      summary: Bulk upload addresses for an entity (only add new addresses)
      description: >
        Updates an entity by bulk uploading addresses. The full JSON input must
        include the updated entity

        details along with a multi-chain addresses mapping. The addresses object
        is keyed by blockchain type

        (for example, `evm`, `bitcoin`, `solana`, etc.) and each value is an
        array of address strings.


        **Example Input Explanation:**

        - **addresses:** A map where each key is a chain identifier and the
        value is an array of valid hexadecimal
          addresses (or formatted address strings for non-EVM chains).
        - Use the same JSON format regardless of whether the entity is a user
        entity or an Arkham entity.

        - **Bulk uploads allow up to 100 total addresses per entity. Make sure
        addresses are valid and formatted correctly.**
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >-
            Unique identifier of the entity to update. You can grab it from your
            url `https://intel.arkm.com/explorer/entity/{entityId}`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityUpdateRequest'
            example:
              id: exampleID
              name: Example Entity
              note: Updated note for my entity.
              addresses:
                evm:
                  - '0xC17eF7e2689DFf7D269Ae2C22f857AcD60B42187'
                  - '0x7dCC00d0Da47e6982672CB1C2481A6943737af45'
                  - '0x36e7C3dd82A56192cF24f326361105D28b426d64'
                bitcoin:
                  - >-
                    bc1qd7m42p9w8djak3qeme06stw7ach7hewa88rd6q0rgegw3mdlpl5s5wje56
                solana:
                  - H6r6ShBfuoVYCCb8ZJANFYfR4y1EXr4vTLYPKbmHGxtv
                tron:
                  - TLBsPRBS6WeB6DyzKSNhKXHxaWESeoK44g
                dogecoin:
                  - D5mBhUmsSKTLMNzBCQcqhF4ZVg7RLtJtCS
                ton:
                  - >-
                    0:412451AE5C7AE4A427DA58D02BFE6D3A3DB4602C4C2A87021B60ACA974189577
      responses:
        '200':
          description: Successful update of the entity. Returns the updated entity.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UserEntity'
                  - $ref: '#/components/schemas/ArkhamEntity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /tx/{hash}:
    get:
      operationId: getTransaction
      tags:
        - Transaction
      summary: Get transaction details
      description: Returns transaction details by hash
      security:
        - ApiKeyAuth: []
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transaction details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TxDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /arkm/circulating:
    get:
      operationId: getArkmCirculating
      tags:
        - ARKM
      summary: Get ARKM circulating supply
      description: >
        Retrieves the circulating supply of ARKM tokens based on the current
        time
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful retrieval of circulating supply
          content:
            application/json:
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /token/top:
    get:
      operationId: getTopTokens
      tags:
        - Token exchange movements
      summary: >-
        Retrieves a ranked list of tokens based on trading volume, inflows,
        outflows, netflows, price, or other metrics over a specified time
        interval. Results can be sorted, filtered by chain, market cap, or token
        ID, and paginated for flexible queries.
      description: >
        Retrieves a list of top tokens based on various query filters.


        **Filter parameters:**

        - **timeframe**: Required time interval for token data. Valid values:
        "1h", "6h", "12h", "24h", "7d".

        - **orderByAgg**: Aggregation field to order tokens by.

        Valid values: "volume", "inflow", "outflow", "volumeDex", "volumeCex",
        "inflowDex", "inflowCex", "outflowDex", "outflowCex", "netflowDex",
        "netflowCex", "netflow", "netflowVolumeRatio", "netflowVolumeRatioDex",
        "netflowVolumeRatioCex", "price".

        - **orderByDesc**: Sorting direction. Must be "true" for descending or
        "false" for ascending.

        - **orderByPercent**: Whether to order results by percentage change.
        Must be "true" or "false".

        - **from**: Starting index for pagination.

        - **size**: Number of results to return.

        - **chains**: Comma-separated list of blockchain chains (e.g.,
        "ethereum,bsc").

        - **minVolume**: Minimum trading volume (float; default is 0).

        - **maxVolume**: Maximum trading volume (float; optional).

        - **minMarketCap**: Minimum market capitalization (float; default is 0).

        - **maxMarketCap**: Maximum market capitalization (float; optional).

        - **numReferencePeriods**: Number of reference periods, defaults to
        "auto".

        - **tokenIds**: Comma-separated list of token IDs to filter by
        (optional).
      security:
        - ApiKeyAuth: []
      parameters:
        - name: timeframe
          in: query
          required: true
          schema:
            type: string
            enum:
              - 1h
              - 6h
              - 12h
              - 24h
              - 7d
          description: Time interval for token data.
        - name: orderByAgg
          in: query
          required: true
          schema:
            type: string
            enum:
              - volume
              - inflow
              - outflow
              - volumeDex
              - volumeCex
              - inflowDex
              - inflowCex
              - outflowDex
              - outflowCex
              - netflowDex
              - netflowCex
              - netflow
              - netflowVolumeRatio
              - netflowVolumeRatioDex
              - netflowVolumeRatioCex
              - price
          description: Aggregation field to order tokens by.
        - name: orderByDesc
          in: query
          required: true
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: >-
            Sorting direction flag. Use "true" for descending, "false" for
            ascending.
        - name: orderByPercent
          in: query
          required: true
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Whether to order results by percentage change.
        - name: from
          in: query
          required: true
          schema:
            type: integer
            default: 0
          description: Starting index for pagination.
        - name: size
          in: query
          required: true
          schema:
            type: integer
            default: 10
          description: Number of results to return.
        - name: chains
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of blockchain chains (e.g., "ethereum,bsc").
        - name: minVolume
          in: query
          required: false
          schema:
            type: number
            default: 0
          description: Minimum volume filter.
        - name: maxVolume
          in: query
          required: false
          schema:
            type: number
          description: Maximum volume filter.
        - name: minMarketCap
          in: query
          required: false
          schema:
            type: number
            default: 0
          description: Minimum market capitalization filter.
        - name: maxMarketCap
          in: query
          required: false
          schema:
            type: number
          description: Maximum market capitalization filter.
        - name: numReferencePeriods
          in: query
          required: false
          schema:
            type: string
            default: auto
          description: Number of reference periods (default "auto").
        - name: tokenIds
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful retrieval of top tokens.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tokens:
                    type: array
                    items:
                      $ref: '#/components/schemas/TopToken'
                  total:
                    type: integer
                    example: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/responses/InternalServerError'
  /intelligence/address/{address}:
    get:
      operationId: getAddressIntelligence
      tags:
        - Intelligence
      summary: Get intelligence about an address
      description: Returns intelligence data for the specified address.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: The address to lookup.
        - name: chain
          in: query
          schema:
            type: string
          description: Optional chain parameter.
      responses:
        '200':
          description: Address intelligence returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /intelligence/address/{address}/all:
    get:
      operationId: getAllAddressIntelligence
      tags:
        - Intelligence
      summary: Get all intelligence about an address across chains
      description: |
        Returns multi-chain intelligence for the provided address.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: The address to lookup.
        - name: tags
          in: query
          schema:
            type: string
          description: If "true", include extra enrichment (e.g. tags).
      responses:
        '200':
          description: Multi-chain intelligence for the address.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Address'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /intelligence/address_enriched/{address}/all:
    get:
      operationId: getAllAddressIntelligenceWithExtraEnrichment
      tags:
        - Intelligence
      summary: >-
        Get intelligence about an address on all chains with additional address
        information
      description: >
        Similar to `/intelligence/address_enriched/{address}`, but aggregates
        data across **every supported chain**. By default, includes tags, entity
        predictions, and cluster IDs. Use query parameters to exclude specific
        enrichments.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: includeTags
          in: query
          description: >-
            Include populated tag details (default: true). Set to 'false' to
            exclude.
          schema:
            type: boolean
            default: true
        - name: includeEntityPredictions
          in: query
          description: >-
            Include predicted entity information (default: true). Set to 'false'
            to exclude.
          schema:
            type: boolean
            default: true
        - name: includeClusters
          in: query
          description: 'Include cluster IDs (default: true). Set to ''false'' to exclude.'
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: >-
            Address intelligence with extra enrichment fields (tags, cluster
            IDs, entity predictions) per chain
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Address'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /intelligence/address_enriched/{address}:
    get:
      operationId: getAddressIntelligenceWithExtraEnrichment
      tags:
        - Intelligence
      summary: Get intelligence about an address with additional address information
      description: >
        Similar to `/intelligence/address/{address}`, but includes additional
        address information (tags, cluster IDs, entity predictions). By default,
        includes tags, entity predictions, and cluster IDs. Use query parameters
        to exclude specific enrichments.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: chain
          in: query
          schema:
            type: string
        - name: includeTags
          in: query
          description: >-
            Include populated tag details (default: true). Set to 'false' to
            exclude.
          schema:
            type: boolean
            default: true
        - name: includeEntityPredictions
          in: query
          description: >-
            Include predicted entity information (default: true). Set to 'false'
            to exclude.
          schema:
            type: boolean
            default: true
        - name: includeClusters
          in: query
          description: 'Include cluster IDs (default: true). Set to ''false'' to exclude.'
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Address intelligence with extra enrichment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressEnriched'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /intelligence/entity/{entity}:
    get:
      operationId: getEntityIntelligence
      tags:
        - Intelligence
      summary: Get intelligence about an entity
      description: |
        Returns top-level entity information, including associated tags.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Entity intelligence
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /intelligence/entity/{entity}/summary:
    get:
      operationId: getEntityIntelligenceSummary
      tags:
        - Intelligence
      summary: Get entity summary statistics
      description: >
        Returns precomputed or calculated summary statistics for the specified
        entity, including:

        - Total number of unique addresses (deduplicated across chains)

        - Total balance in USD across all chains

        - Total transfer volume in USD

        - First and last transfer timestamps


        **Supports both Arkham entities and user entities:**

        - For Arkham entities (e.g., "binance"): Returns precomputed data when
        available, falls back to calculation

        - For user entities: Always calculates on the fly

        - Includes user-added addresses for Arkham entities when authenticated


        **Shareable user entities:** If a user entity is marked as shareable,
        any authenticated or unauthenticated user can access the summary.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
          description: The entity ID (Arkham entity like "binance" or user entity)
      responses:
        '200':
          description: Entity summary statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /intelligence/entity_predictions/{entity}:
    get:
      operationId: getEntityPredictions
      tags:
        - Intelligence
      summary: Get predictions for an entity
      description: >
        Returns predicted addresses for the specified entity. These predictions
        are generated using machine learning algorithms to identify addresses
        that may belong to the entity based on transaction patterns and other
        blockchain data. Returns up to 1000 predictions per entity, sorted by
        USD balance.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
          description: The entity ID to get predictions for.
      responses:
        '200':
          description: Entity predictions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EntityPrediction'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /intelligence/contract/{chain}/{address}:
    get:
      operationId: getContractIntelligence
      tags:
        - Intelligence
      summary: Get intelligence about a contract
      description: Returns contract metadata for the specified chain & address.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: chain
          in: path
          required: true
          schema:
            type: string
        - name: address
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Contract intelligence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /intelligence/token/{id}:
    get:
      operationId: getTokenIntelligence
      tags:
        - Intelligence
      summary: Get intelligence on a token by CoinGecko pricing ID
      description: |
        Retrieve basic token info using the CoinGecko pricing ID.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The CoinGecko ID (e.g. "bitcoin", "ethereum").
      responses:
        '200':
          description: Token intelligence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenBasicInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /intelligence/token/{chain}/{address}:
    get:
      operationId: getTokenIntelligenceByChainAndAddress
      tags:
        - Intelligence
      summary: Get intelligence on a token by chain/address
      description: |
        Retrieve basic token info using chain + contract address.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: chain
          in: path
          required: true
          schema:
            type: string
        - name: address
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Token intelligence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenBasicInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tag/{id}/params:
    get:
      operationId: getTagParams
      tags:
        - Intelligence
      summary: Get tag parameters
      description: >
        Returns a list of all unique tag parameter combinations for the
        specified tag.


        **Pagination parameters:**

        - **limit**: Number of items to return per page (1-1000, default 100)

        - **offset**: Number of items to skip from the beginning (default 0)
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The tag identifier
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
          description: Number of items to return per page (1-1000, default 100)
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of items to skip from the beginning (default 0)
      responses:
        '200':
          description: Tag parameters returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PopulatedTag'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /tag/{id}/summary:
    get:
      operationId: getTagSummary
      tags:
        - Intelligence
      summary: Get tag summary statistics
      description: >
        Returns precomputed summary statistics for the specified tag, including
        total counts of addresses, entities, and unique tag parameters.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The tag identifier
      responses:
        '200':
          description: Tag summary statistics returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /history/entity/{entity}:
    get:
      operationId: getEntityHistory
      tags:
        - History
      summary: Get historical data for an entity
      description: Returns historical USD snapshots for the specified entity.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
          description: The entity ID.
      responses:
        '200':
          description: Historical data for the entity.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    time:
                      type: string
                      format: date-time
                      example: '2025-08-26T10:01:30.071Z'
                    usd:
                      type: number
                      example: 20468.10700821187
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /history/address/{address}:
    get:
      operationId: getAddressHistory
      tags:
        - History
      summary: Get historical data for an address
      description: Returns historical USD snapshots for the specified address.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: The address to lookup.
        - name: chain
          in: query
          schema:
            type: string
          description: Optional chain parameter.
      responses:
        '200':
          description: Historical data for the address.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    time:
                      type: string
                      format: date-time
                      example: '2025-08-18T16:34:32Z'
                    usd:
                      type: number
                      example: 20468.10700821187
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /portfolio/entity/{entity}:
    get:
      operationId: getEntityPortfolioHistory
      tags:
        - Portfolio
      summary: Get entity portfolio history
      description: >
        Retrieves historical portfolio snapshots for the specified entity across
        chains.


        **Filter parameters:**

        - **entity**: The unique identifier of the entity. This can be a user
        entity ID or another entity.

        - **time**: Unix timestamp in milliseconds representing the time for
        which to retrieve the portfolio history. The time will be truncated to
        the start of the UTC day.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
          description: The entity identifier.
        - name: time
          in: query
          required: true
          schema:
            type: integer
          description: Unix timestamp in milliseconds (e.g. 1672531200000).
      responses:
        '200':
          description: Portfolio history retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityPortfolioHistory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Internal server error.
  /portfolio/address/{address}:
    get:
      operationId: getAddressPortfolioHistory
      tags:
        - Portfolio
      summary: Get address portfolio history
      description: >
        Retrieves historical portfolio snapshots for the specified address
        across chains.


        **Filter parameters:**

        - **address**: The blockchain address for which to retrieve portfolio
        history.

        - **time**: Unix timestamp in milliseconds representing the time for
        which to retrieve the portfolio history. The time is truncated to the
        start of the UTC day.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: The blockchain address.
        - name: time
          in: query
          required: true
          schema:
            type: integer
          description: Unix timestamp in milliseconds (e.g. 1672531200000).
      responses:
        '200':
          description: Portfolio history retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressPortfolioHistory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Internal server error.
  /portfolio/timeSeries/entity/{entity}:
    get:
      operationId: getEntityPortfolioHistoryTimeSeries
      tags:
        - Portfolio
      summary: Get daily time series data for an entity's token
      description: >
        Returns daily snapshots (in UTC) of the specified entity's holdings of a
        given token.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
        - name: pricingId
          in: query
          schema:
            type: string
          description: CoinGecko ID for the token
      responses:
        '200':
          description: A daily time series of balances
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    id:
                      type: string
                      example: ethereum
                    name:
                      type: string
                      example: Ethereum
                    symbol:
                      type: string
                      example: eth
                    balance:
                      type: number
                      example: 240164.91278818768
                    price:
                      type: number
                      example: 2651.05
                    usd:
                      type: number
                      example: 636689192.047125
  /portfolio/timeSeries/address/{address}:
    get:
      operationId: getAddressPortfolioHistoryTimeSeries
      tags:
        - Portfolio
      summary: Get daily time series data for an address's token
      description: >
        Returns daily snapshots (in UTC) of the specified address's holdings of
        a given token.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: pricingId
          in: query
          schema:
            type: string
          description: CoinGecko ID for the token
      responses:
        '200':
          description: A daily time series of balances
          content:
            application/json:
              schema:
                type: object
  /token/holders/{pricing_id}:
    get:
      operationId: getTopTokenHolders
      tags:
        - Token
      summary: Get top token holders by pricing ID
      description: >-
        Returns top token holders for the token identified by its CoinGecko
        pricing ID.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: pricing_id
          in: path
          required: true
          schema:
            type: string
          description: The CoinGecko pricing ID (e.g., "bitcoin", "ethereum").
        - name: groupByEntity
          in: query
          schema:
            type: boolean
          description: If true, group results by entity.
      responses:
        '200':
          description: Top token holders data
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    $ref: '#/components/schemas/TokenBasicInfo'
                  totalSupply:
                    type: object
                    additionalProperties:
                      type: number
                  holders:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: object
                        properties:
                          address:
                            $ref: '#/components/schemas/Address'
                          balance:
                            type: number
                            example: 67602115.48639515
                          usd:
                            type: number
                            example: 299686262141.58344
                          pctOfCap:
                            type: number
                            example: 0.5600512926552481
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /token/holders/{chain}/{address}:
    get:
      operationId: getTopTokenHoldersByChainAndAddress
      tags:
        - Token
      summary: Get top token holders by chain and address
      description: >-
        Returns top token holders for the token at the specified contract
        address on the given chain.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: chain
          in: path
          required: true
          schema:
            type: string
          description: The chain (e.g. "ethereum").
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: The token contract address.
        - name: groupByEntity
          in: query
          schema:
            type: boolean
          description: If true, group results by entity.
      responses:
        '200':
          description: Top token holders data
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /token/trending:
    get:
      operationId: getTrendingTokens
      tags:
        - Token
      summary: Get trending tokens
      description: Returns a list of currently trending tokens across multiple chains.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: An array of trending tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrendingToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /token/trending/{id}:
    get:
      operationId: getTrendingToken
      tags:
        - Token
      summary: Get a single trending token by ID
      description: >-
        Returns a single trending token, identified by a specific ID (e.g.,
        "bitcoin", "ethereum").
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The pricing ID (CoinGecko ID).
      responses:
        '200':
          description: A single trending token object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendingToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /marketdata/altcoin_index:
    get:
      operationId: getAltcoinIndex
      tags:
        - Market Data
      summary: Get Altcoin Index
      description: >
        Retrieves the altcoin index calculated by comparing the percentage
        change of top altcoins to Bitcoin's percentage change over the last 90
        days.

        The index represents the count of altcoins outperforming Bitcoin.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful retrieval of altcoin index
          content:
            application/json:
              schema:
                type: object
                properties:
                  altcoinIndex:
                    type: integer
                    example: 28
        '500':
          description: Internal Server Error - Error calculating altcoin index
  /token/arkham_exchange_tokens:
    get:
      operationId: getArkhamExchangeTokens
      tags:
        - ARKM
      summary: Get Arkham Exchange tokens
      description: >-
        Returns a JSON object with token symbols/addresses as keys and booleans
        as values.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Object mapping token => boolean
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /token/top_flow/{id}:
    get:
      operationId: getTokenTopFlow
      tags:
        - Token
      summary: Get top flow for a token by pricing ID
      description: >
        Returns the top inflows/outflows for the specified token ID, aggregated
        by address. **Rate Limit**: This endpoint has a stricter rate limit of 1
        request per second.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: timeLast
          in: query
          schema:
            type: string
          description: e.g. 24h, 7d, 1h
        - name: chains
          in: query
          schema:
            type: string
      responses:
        '200':
          description: An array of top flows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopFlowItem'
  /token/top_flow/{chain}/{address}:
    get:
      operationId: getTokenTopFlowByChain
      tags:
        - Token
      summary: Get top token flow
      description: >
        Retrieves the top token flow (in USD and value) for the specified chain
        and address over a given duration.


        **Rate Limit**: This endpoint has a stricter rate limit of 1 request per
        second.


        **Filter parameters:**

        - **chain**: The blockchain chain identifier (e.g., ethereum, bitcoin).

        - **address**: The token address or holder address.

        - **timeLast**: A duration string (e.g., "24h", "7d") representing the
        time window to consider.

        - **chains** (optional): Comma-separated list of chains to further
        filter the results.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: chain
          in: path
          required: true
          schema:
            type: string
          description: The blockchain chain (e.g., ethereum, bitcoin).
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: The token address or holder address.
        - name: timeLast
          in: query
          required: true
          schema:
            type: string
          description: Duration string representing the time window (e.g., "24h", "7d").
        - name: id
          in: query
          required: true
          schema:
            type: string
          description: pricingID of a token, e.g. "arkham"
      responses:
        '200':
          description: Top token flow data retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopFlowItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Internal server error.
  /token/volume/{id}:
    get:
      operationId: getTokenVolume
      tags:
        - Token
      summary: Get volume for a token by pricing ID
      description: >
        Returns aggregated volume data for the specified token ID, optionally
        broken down by time granularity. **Rate Limit**: This endpoint has a
        stricter rate limit of 1 request per second.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: timeLast
          in: query
          schema:
            type: string
        - name: granularity
          in: query
          schema:
            type: string
            enum:
              - 1h
              - 24h
              - 7d
              - 1w
      responses:
        '200':
          description: A list of volume data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenVolumeItem'
  /token/volume/{chain}/{address}:
    get:
      operationId: getTokenVolumeByChain
      tags:
        - Token
      summary: Get volume for a token by chain/address
      description: >
        Returns aggregated volume data for the specified token contract on a
        certain chain. **Rate Limit**: This endpoint has a stricter rate limit
        of 1 request per second.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: chain
          in: path
          required: true
          schema:
            type: string
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: timeLast
          in: query
          schema:
            type: string
        - name: granularity
          in: query
          schema:
            type: string
            enum:
              - 1h
              - 24h
              - 7d
              - 1w
      responses:
        '200':
          description: A list of volume data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenVolumeItem'
  /token/balance/{id}:
    get:
      operationId: getTokenBalance
      tags:
        - Token
      summary: Get token balance (all chains) for an entity or address
      description: >
        Returns the aggregated token balance for either an entity or address,
        across all chains.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: CoinGecko pricing ID (e.g. "bitcoin")
        - name: entityID
          in: query
          schema:
            type: string
        - name: address
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Basic balance info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenBalanceItem'
  /token/balance/{chain}/{address}:
    get:
      operationId: getTokenBalanceByChain
      tags:
        - Token
      summary: Get token balance for an entity or address, for a specific chain/address
      description: >
        Returns the aggregated token balance for either an entity or address,
        across all chains, but identified by the specific token contract.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: chain
          in: path
          required: true
          schema:
            type: string
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: entityID
          in: query
          schema:
            type: string
        - name: addressQuery
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Basic balance info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenBalanceItem'
  /networks/status:
    get:
      operationId: getNetworkStatus
      tags:
        - Networks
      summary: Get status for all supported networks
      description: Returns an array of current status information for each network.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Array of network statuses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /networks/history/{chain}:
    get:
      operationId: getNetworkHistory
      tags:
        - Networks
      summary: Get historical network data
      description: Returns historical quotes for the specified chain.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: chain
          in: path
          required: true
          schema:
            type: string
          description: The chain (e.g., "ethereum", "bitcoin").
      responses:
        '200':
          description: Historical quotes for the chain
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TokenHistoricalQuote'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /balances/address/{address}:
    get:
      operationId: getAddressBalances
      tags:
        - Balances
      summary: Get token balances for an address
      description: >
        Returns token balances for the specified address, optionally filtered by
        chains.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: chains
          in: query
          schema:
            type: string
          description: Comma-separated chain list
      responses:
        '200':
          description: Balances for the address
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalBalance:
                    type: object
                  balances:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/BalanceDetail'
  /balances/entity/{entity}:
    get:
      operationId: getEntityBalances
      tags:
        - Balances
      summary: Get token balances for an entity
      description: >
        Returns token balances for the specified entity, optionally filtered by
        chains.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
        - name: chains
          in: query
          schema:
            type: string
          description: Comma-separated chain list
      responses:
        '200':
          description: Balances for the entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalBalance:
                    type: object
                  balances:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/BalanceDetail'
  /loans/address/{address}:
    get:
      operationId: getAddressLoans
      tags:
        - Loans
      summary: Get loan/borrow positions for an address
      description: >
        Returns an overview of loaned/supplied/borrowed assets for a given
        address.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: chains
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Loan details
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalPositions:
                    type: object
                    additionalProperties:
                      type: number
                  balances:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/LoanPosition'
  /loans/entity/{entity}:
    get:
      operationId: getEntityLoans
      tags:
        - Loans
      summary: Get loan/borrow positions for an entity
      description: >
        Returns an overview of loaned/supplied/borrowed assets for a given
        entity.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
        - name: chains
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Loan details for the entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalPositions:
                    type: object
                    additionalProperties:
                      type: number
                  balances:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        $ref: '#/components/schemas/LoanPosition'
  /counterparties/address/{address}:
    get:
      operationId: getAddressCounterparty
      tags:
        - Counterparties
      summary: Get counterparties for an address
      description: >
        Returns aggregated info about top counterparties by volume (in/out).


        **Rate Limit**: This endpoint has a stricter rate limit of 1 request per
        second.


        **Filter parameters:**

        - **flow**: Direction of the transfer. Valid values are "in", "out", or
        "either".

        - **limit**: Maximum number of results to return.

        - **chains**: Comma-separated list of chains (e.g. "ethereum,bsc").

        - **tokens**: Comma-separated list of token addresses or token IDs. E.g.
        "ethereum", "usd-coin", or "0x...tokenAddress".

        - **timeLast**: Time range filter using relative durations (e.g. "24h",
        "7d", "30d"). Cannot be used with timeGte/timeLte.

        - **timeGte/timeLte**: Filter from/to a specific timestamp in
        milliseconds. Cannot be used with 'timeLast' parameter.

        - **valueGte/valueLte**: Numeric filters on the raw token amount
        (on-chain units).

        - **usdGte/usdLte**: Numeric filters on the historical USD value.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: The address to get counterparties for.
        - name: flow
          in: query
          schema:
            type: string
            enum:
              - in
              - out
              - either
          description: >
            Transfer direction: "in" for incoming, "out" for outgoing, "either"
            for both directions.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          description: |
            Maximum number of counterparties to return (between 1 and 1000).
        - name: chains
          in: query
          schema:
            type: string
          description: |
            Comma-separated list of chains. For example: "ethereum,bsc".
        - name: tokens
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of token addresses or token IDs. E.g.
            "ethereum", "usd-coin", or "0x...tokenAddress".
        - name: timeLast
          in: query
          schema:
            type: string
          description: >
            Time range filter using relative durations. Examples: "24h", "7d",
            "30d". Cannot be used with timeGte/timeLte.
        - name: timeGte
          in: query
          schema:
            type: string
          description: >
            Time range filter (from) in milliseconds (e.g. `1696630274000`).
            Cannot be used with 'timeLast' parameter.
        - name: timeLte
          in: query
          schema:
            type: string
          description: >
            Time range filter (to) in milliseconds (e.g. `1696716674000`).
            Cannot be used with 'timeLast' parameter.
        - name: valueGte
          in: query
          schema:
            type: number
          description: |
            Minimum raw token value (on-chain units).
        - name: valueLte
          in: query
          schema:
            type: number
          description: |
            Maximum raw token value (on-chain units).
        - name: usdGte
          in: query
          schema:
            type: number
          description: |
            Minimum historical USD value.
        - name: usdLte
          in: query
          schema:
            type: number
          description: |
            Maximum historical USD value.
      responses:
        '200':
          description: Counterparty data
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/Counterparty'
  /counterparties/entity/{entity}:
    get:
      operationId: getEntityCounterparty
      tags:
        - Counterparties
      summary: Get counterparties for an entity
      description: >
        Returns aggregated info about top counterparties by volume (in/out).


        **Rate Limit**: This endpoint has a stricter rate limit of 1 request per
        second.


        **Filter parameters:**

        - **flow**: Direction of the transfer. Valid values are "in", "out", or
        "either".

        - **limit**: Maximum number of results to return.

        - **chains**: Comma-separated list of chains (e.g. "ethereum,bsc").

        - **tokens**: Comma-separated list of token addresses or token IDs. E.g.
        "ethereum", "usd-coin", or "0x...tokenAddress".

        - **timeLast**: Time range filter using relative durations (e.g. "24h",
        "7d", "30d"). Cannot be used with timeGte/timeLte.

        - **timeGte/timeLte**: Filter from/to a specific timestamp in
        milliseconds. Cannot be used with 'timeLast' parameter.

        - **valueGte/valueLte**: Numeric filters on the raw token amount
        (on-chain units).

        - **usdGte/usdLte**: Numeric filters on the historical USD value.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
          description: The entity ID to get counterparties for.
        - name: flow
          in: query
          schema:
            type: string
            enum:
              - in
              - out
              - either
          description: >
            Transfer direction: "in" for incoming, "out" for outgoing, "either"
            for both directions.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          description: |
            Maximum number of counterparties to return (between 1 and 1000).
        - name: chains
          in: query
          schema:
            type: string
          description: |
            Comma-separated list of chains. For example: "ethereum,bsc".
        - name: tokens
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of token addresses or token IDs. E.g.
            "ethereum", "usd-coin", or "0x...tokenAddress".
        - name: timeLast
          in: query
          schema:
            type: string
          description: >
            Alternative time range filter using relative durations. Examples:
            "24h", "7d", "30d". Cannot be used with timeGte/timeLte.
        - name: timeGte
          in: query
          schema:
            type: string
          description: >
            Time range filter (from) in milliseconds (e.g. `1696630274000`).
            Cannot be used with 'timeLast' parameter.
        - name: timeLte
          in: query
          schema:
            type: string
          description: >
            Time range filter (to) in milliseconds (e.g. `1696716674000`).
            Cannot be used with 'timeLast' parameter.
        - name: valueGte
          in: query
          schema:
            type: number
          description: |
            Minimum raw token value (on-chain units).
        - name: valueLte
          in: query
          schema:
            type: number
          description: |
            Maximum raw token value (on-chain units).
        - name: usdGte
          in: query
          schema:
            type: number
          description: |
            Minimum historical USD value.
        - name: usdLte
          in: query
          schema:
            type: number
          description: |
            Maximum historical USD value.
      responses:
        '200':
          description: Counterparty data
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/Counterparty'
  /user/labels:
    get:
      operationId: getLabels
      tags:
        - Labels
      summary: Get user labels
      description: |
        Retrieves a list of labels for the authenticated user.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: A list of labels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Label'
              example:
                - name: Ethereum Label
                  note: Label for Ethereum address
                  address: '0xABCDEF1234567890'
                  chainType: evm
                - name: Bitcoin Label
                  note: Label for Bitcoin address
                  address: bc1qexamplebitcoinaddress
                  chainType: bitcoin
                - name: Tron Label
                  note: Label for Tron address
                  address: TExampleTronAddress
                  chainType: tron
                - name: Solana Label
                  note: Label for Solana address
                  address: ExampleSolanaAddressBase58
                  chainType: solana
                - name: Dogecoin Label
                  note: Label for Dogecoin address
                  address: DExampleDogecoinAddress
                  chainType: dogecoin
                - name: Ton Label
                  note: Label for Ton address
                  address: 0:EXAMPLETONADDRESS
                  chainType: ton
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createLabels
      tags:
        - Labels
      summary: Create labels for the user
      description: >
        Creates one or more labels for the authenticated user.

        Each label must include:

        - **name**: A string (maximum 256 characters)

        - **note**: A string (maximum 1024 characters)

        - **address**: The label's address

        - **chainType**: The type of the chain (e.g., "evm", "bitcoin", "tron",
        "solana", "dogecoin", "ton")
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/LabelInput'
            example:
              - name: Ethereum Label
                note: Label for Ethereum address
                address: '0xABCDEF1234567890'
                chainType: evm
              - name: Bitcoin Label
                note: Label for Bitcoin address
                address: bc1qexamplebitcoinaddress
                chainType: bitcoin
              - name: Tron Label
                note: Label for Tron address
                address: TExampleTronAddress
                chainType: tron
              - name: Solana Label
                note: Label for Solana address
                address: ExampleSolanaAddressBase58
                chainType: solana
              - name: Dogecoin Label
                note: Label for Dogecoin address
                address: DExampleDogecoinAddress
                chainType: dogecoin
              - name: Ton Label
                note: Label for Ton address
                address: 0:EXAMPLETONADDRESS
                chainType: ton
      responses:
        '200':
          description: Successfully created labels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Label'
              example:
                - name: Ethereum Label
                  note: Label for Ethereum address
                  address: '0xABCDEF1234567890'
                  chainType: evm
                - name: Bitcoin Label
                  note: Label for Bitcoin address
                  address: bc1qexamplebitcoinaddress
                  chainType: bitcoin
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteLabels
      tags:
        - Labels
      summary: Delete multiple user labels
      description: >
        Deletes multiple labels for the authenticated user.

        The **labels** query parameter should be a comma-separated list of label
        identifiers,

        where each identifier is in the format **address:chainType**.

        For example:
        `"0xABCDEF1234567890:evm,bc1qexamplebitcoinaddress:bitcoin"`.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: labels
          in: query
          required: true
          schema:
            type: string
          description: A comma-separated list of label identifiers to delete.
      responses:
        '200':
          description: Successfully deleted the specified labels.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /user/labels/{address}:
    put:
      operationId: updateLabel
      tags:
        - Labels
      summary: Update a user label
      description: >
        Updates an existing label for the authenticated user.

        The label to update is identified by the **address** provided in the
        URL,

        which must include the chain type appended after a colon (e.g.,
        `"0xABCDEF1234567890:evm"`).

        The request body should include the updated **name**, **note**,
        **address**, and **chainType**.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: >
            The address of the label to update with its chain type appended
            using a colon. Example: `"0xABCDEF1234567890:evm"`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelInput'
            example:
              name: Updated Ethereum Label
              note: Updated note for Ethereum label.
              address: '0xABCDEF1234567890'
              chainType: evm
      responses:
        '200':
          description: Successfully updated the label.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
              example:
                name: Updated Ethereum Label
                note: Updated note for Ethereum label.
                address: '0xABCDEF1234567890'
                chainType: evm
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteLabel
      tags:
        - Labels
      summary: Delete a user label
      description: >
        Deletes a specific label for the authenticated user.

        The label is identified by the **address** path parameter which includes
        the chain type.

        Example format: `"0xABCDEF1234567890:evm"`.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: >
            The label address with chain type appended using a colon. Example:
            `"0xABCDEF1234567890:evm"`.
      responses:
        '200':
          description: Label deleted successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /flow/address/{address}:
    get:
      operationId: getAddressFlow
      tags:
        - Flow
      summary: Get USD flow data for an address
      description: >
        Retrieves historical USD flow snapshots for the specified address across
        all supported chains.


        **Flow data includes:**

        - **Inflow**: USD value flowing into the address per time period

        - **Outflow**: USD value flowing out of the address per time period

        - **Cumulative flows**: Running totals of inflows and outflows over time


        **Filter parameters:**

        - **address**: The blockchain address to get flow data for. Can be a
        comma-separated list of addresses.

        - **chains**: Optional comma-separated list of chains to filter results
        (e.g. "ethereum,bsc").
      security:
        - ApiKeyAuth: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: >
            The blockchain address or comma-separated list of addresses to get
            flow data for. For example: "0x123abc" or "0x123abc,0x456def".
        - name: chains
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of chains to filter results. For example:
            "ethereum,bsc,polygon". If not provided, returns data for all
            supported chains.
      responses:
        '200':
          description: Flow data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                description: >-
                  A map where each key is a chain name and the value is an array
                  of flow snapshots
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/FlowSnapshot'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Internal server error
  /flow/entity/{entity}:
    get:
      operationId: getEntityFlow
      tags:
        - Flow
      summary: Get USD flow data for an entity
      description: >
        Retrieves historical USD flow snapshots for the specified entity across
        all supported chains.


        **Flow data includes:**

        - **Inflow**: USD value flowing into the entity per time period

        - **Outflow**: USD value flowing out of the entity per time period

        - **Cumulative flows**: Running totals of inflows and outflows over time


        **Entity types supported:**

        - User entities (custom entities created by users)

        - Arkham entities (pre-labeled entities in the Arkham database)


        **Filter parameters:**

        - **entity**: The entity ID to get flow data for

        - **chains**: Optional comma-separated list of chains to filter results
        (e.g. "ethereum,bsc").
      security:
        - ApiKeyAuth: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
          description: >
            The entity ID to get flow data for. Can be a user entity ID or an
            Arkham entity identifier.
        - name: chains
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of chains to filter results. For example:
            "ethereum,bsc,polygon". If not provided, returns data for all
            supported chains.
      responses:
        '200':
          description: Flow data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                description: >-
                  A map where each key is a chain name and the value is an array
                  of flow snapshots
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/FlowSnapshot'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Internal server error
