# Transfers

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.

## Get transfers

 - [GET /transfers](https://docs.intel.arkm.com/openapi/transfers/gettransfers.md): 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).

## WebSocket Transfer Streaming

 - [GET /ws/transfers](https://docs.intel.arkm.com/openapi/transfers/getwebsockettransfers.md): 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

## Get a simple histogram of transfers (Public)

 - [GET /transfers/histogram/simple](https://docs.intel.arkm.com/openapi/transfers/gettransfershistogramsimple.md): 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.

## Get a detailed histogram of transfers (API Only)

 - [GET /transfers/histogram](https://docs.intel.arkm.com/openapi/transfers/gettransfershistogram.md): 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).

## Get swaps

 - [GET /swaps](https://docs.intel.arkm.com/openapi/transfers/getswaps.md): 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).