> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metastreams.io/llms.txt
> Use this file to discover all available pages before exploring further.

# spot.transfers

> Streams every wallet-to-wallet transfer that matches a filter on token, wallet, sender, recipient or amount.

Streams every transfer between two wallets that matches the subscription's filters, in real time. Each transfer is tested once, as it happens, and `{}` matches every transfer on every chain.

Subscribe on an open stream connection. See [WebSocket streams](https://docs.metastreams.io/streams/overview.md) for connections, frames and reconnection, and [Filtering streams](https://docs.metastreams.io/streams/filters.md) for how keys, lists and ranges combine.

## Filters

| Group | Keys |
| - | - |
| Scope | `chains`; `tokens`, `wallets` (either side), `senders`, `recipients` (addresses) |
| Transfer | `native` (`true` for the chain's native asset, `false` for a token); `amount` (in token units) |
| Token state | `token`, which takes any [`spot.tokens` filter](https://docs.metastreams.io/reference/streams/spot-tokens#filters) |
| Exclude | `exclude.wallets` (either side), `exclude.tokens` |

### Addresses

`tokens`, `wallets`, `senders` and `recipients` each cover every chain in their address family that `chains` includes.

* `wallets` matches a transfer whose sender or recipient is in the list. `senders` and `recipients` each match one side.
* Omit a list to match every address. An empty list is rejected.
* These four lists have no limit of their own; only the [address limit](https://docs.metastreams.io/streams/filters.md#address-limits) applies. `chains`, `exclude.wallets` and `exclude.tokens` take at most 100 values each.
* A transfer that matches two addresses of one subscription, such as its sender and its recipient, is sent once.

### Native transfers

A native transfer moves the chain's gas asset and has no token, so it does not match `tokens` or `token`. `native: true` combined with `tokens` or `token` is rejected.

### Token state

`token` tests the latest state of the transferred token, as on [`spot.trades`](https://docs.metastreams.io/reference/streams/spot-trades#token-state). A token has a state only after it changes while a subscription with a `token` key is open, and the state expires after 15 minutes without a change.

### Values

A transfer has no USD or native value, so the filter has no value keys. `valueUsd` and `valueNative` are rejected like any unknown key.

This channel does not accept `throttleMs` and does not send `exit` frames.

## Message format

Each update's `data` is one transfer.

**chain** `string` *required*

[Chain slug](https://docs.metastreams.io/concepts/chains.md).

**token** `string | null` *required*

Token address; `null` for the chain's native asset.

**sender** `string` *required*

Wallet that sent the transfer.

**recipient** `string` *required*

Wallet that received the transfer.

**amount** `string` *required*

Amount moved, in token units, as a [decimal string](https://docs.metastreams.io/concepts/reading-responses.md#decimals).

**senderBalanceAfter** `string | null` *required*

Sender's balance of the asset after the transaction; `null` when unknown.

**recipientBalanceAfter** `string | null` *required*

Recipient's balance of the asset after the transaction; `null` when unknown.

**transactionHash** `string` *required*

On-chain transaction hash.

**eventIndex** `integer | null` *required*

Position of this transfer within the transaction; `null` for a native transfer on an EVM chain.

**timestamp** `integer` *required*

Execution time, in milliseconds.

No REST endpoint returns transfers, so the stream has no snapshot to merge with.

## Errors

| Code | When |
| - | - |
| `VALIDATION_ERROR` | Any cause listed under [Errors](https://docs.metastreams.io/streams/filters.md#errors); an empty `tokens`, `wallets`, `senders` or `recipients` list; `native: true` with `tokens` or `token`; any `throttleMs` above 0, which this channel does not accept |
| `UNSUPPORTED_CHAIN` | Unsupported chain slug |

```json Wallet theme={null}
{
  "action": "subscribe",
  "channel": "spot.transfers",
  "filters": {
    "chains": ["solana"],
    "wallets": ["8D2YW555vKLbTjhhhJggAEbcioLEGzgiQpFVXq3LxLHA"]
  }
}
```

```json Large token moves theme={null}
{
  "action": "subscribe",
  "channel": "spot.transfers",
  "filters": {
    "chains": ["solana"],
    "native": false,
    "amount": { "min": "1000" },
    "token": { "marketCapUsd": { "max": "5000000" } },
    "exclude": { "tokens": ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"] }
  }
}
```

```json Update theme={null}
{
  "type": "update",
  "channel": "spot.transfers",
  "subscriptionId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "data": {
    "chain": "solana",
    "token": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "sender": "8D2YW555vKLbTjhhhJggAEbcioLEGzgiQpFVXq3LxLHA",
    "recipient": "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5",
    "amount": "250000000",
    "senderBalanceAfter": "750000000",
    "recipientBalanceAfter": "250000000",
    "transactionHash": "5kT9rWc2xQ8mNbV3pL7dHfA1jEuY6gVnX1oB5iC0wQ2rT8yU3iO7pA1sD4fG6hJ9",
    "eventIndex": 3,
    "timestamp": 1789632015120
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.