# WebSocket Transfer Streaming

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

Endpoint: GET /ws/transfers
Version: 1.0.0
Security: ApiKeyAuth

## Response 401 fields (application/json):

  - `error` (string)
    Example: "API key missing or invalid"


## Response 101 fields

## Response 400 fields