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

# Track a deposit

> Follow a transfer to a bank account address from the moment it lands to the naira payout, over a WebSocket.

Paying a [bank account address](https://docs.paj.cash/concepts/bank-account-addresses.md), on Solana
or an EVM chain, needs no API call, which also means there is no order to poll afterwards. To know what
happened to a transfer you sent, subscribe to its transaction signature on the
deposit socket. You get its current state straight away, then a message each
time it moves forward, until the naira reaches the bank account.

The socket runs on [Socket.IO](https://socket.io), on the same host as the REST
API, in the `tx-pool` namespace:

```
wss://api.paj.cash/tx-pool
```

## Connecting

The socket takes the same [API key](https://docs.paj.cash/authentication.md) as the REST API. Send it in
the handshake as `auth.apiKey`, or as an `x-api-key` header if your client sets
headers.

```javascript theme={null}
import { io } from 'socket.io-client';

const socket = io('https://api.paj.cash/tx-pool', {
  auth: { apiKey: process.env.PAJ_API_KEY },
});

socket.on('connect_error', (error) => {
  // "No API key provided", "Invalid API key", or
  // "Could not verify the API key, try again"
  console.error(error.message);
});
```

A connection without a valid key is refused during the handshake and never
opens. The first two messages are permanent: fix the key rather than retrying.
The third means the key could not be checked at that moment, and Socket.IO's
own reconnection will try again.

> [!WARNING]
>
> This is your API key, and the same rules apply as anywhere else: connect from
> your backend, never from a browser bundle or a mobile app a user can read.
> Relay what your users need to see through your own servers.

## Subscribing to a transfer

Once you have sent a transfer, subscribe with what identifies it on its chain:
the transaction signature for a transfer to `address` on Solana, or the
transaction hash for a transfer to `evmAddress` on an EVM chain. The field is
called `signature` either way:

```javascript theme={null}
socket.emit('subscribe', { signature }, (ack) => {
  if (!ack.ok) return console.error(ack.error);

  if (ack.transaction) {
    console.log('Current state:', ack.transaction.stage);
  } else {
    console.log('Not seen yet, waiting for it to land');
  }
});

socket.on('TX_POOL_UPDATE', (update) => {
  console.log(update.signature, update.stage, update.status);

  if (update.stage === 'completed') {
    socket.emit('unsubscribe', { signature: update.signature });
  }
});
```

Subscribe as soon as you have the signature, before Paj has seen the transfer.
That is the normal case: the subscription waits, and the first
`TX_POOL_UPDATE` arrives when the deposit is picked up, usually within seconds
of confirmation. Subscribing late is also fine. A transfer that has already been
paid out is still found, and the acknowledgement carries its final state.

EVM hashes are matched whatever their letter case, so a checksummed hash from a
wallet works as-is. Solana signatures are case-sensitive and must be sent
exactly.

### The acknowledgement

The callback you pass to `subscribe` receives:

**ok** `boolean` *required*

Whether you are now subscribed.

**signature** `string`

The signature you subscribed to, trimmed.

**transaction** `object | null`

Where the transfer stands now, in the same shape as a
[`TX_POOL_UPDATE`](#updates), or `null` when Paj has not seen it yet.

**error** `string`

Why the subscription was refused, when `ok` is `false`. The same message is
also sent as an `ERROR` event.

A subscription is refused when `signature` is missing or longer than 128
characters, or when the connection already watches 50 signatures. Unsubscribe
from transfers that have completed to stay under the limit, or open a second
connection.

## Updates

Every `TX_POOL_UPDATE` carries the whole current state of one transfer, not just
what changed, so you can handle each one on its own.

```json theme={null}
{
  "signature": "5VfYk2vQwH3pTq1eXJ9mWZ8cLkNa7RbDsGtUoPiYhE4xCnM6zV1uS2rAjQ3wK8",
  "chain": "SOLANA",
  "stage": "processing",
  "status": "SWAPPED",
  "mint": "So11111111111111111111111111111111111111112",
  "amount": 0.5,
  "usdcAmount": 71.84,
  "sweepSignature": "3kTq9mW…",
  "swapSignature": "4hNc2pX…",
  "updatedAt": "2026-11-10T09:21:05.412Z"
}
```

**signature** `string` *required*

The transfer you subscribed to.

**chain** `string` *required*

The [chain](https://docs.paj.cash/concepts/chains.md) it was sent on.

**stage** `string` *required*

Where it stands. Build on this field. See [Stages](#stages).

**status** `string` *required*

Paj's own processing step, finer than `stage`. Useful for logs and support,
but the values may change, so don't branch on them.

**mint** `string` *required*

The token that was sent: its mint or contract address.

**amount** `number` *required*

How much of it was sent, in whole tokens rather than base units.

**usdcAmount** `number`

What the transfer was worth in USDC, once it has been swapped or priced.

**fiatAmount** `number`

The naira paid out, in kobo, once known.

**sweepSignature** `string`

The on-chain transaction that moved the funds from the address into Paj's
treasury, once made.

**swapSignature** `string`

The on-chain swap into USDC, for tokens that needed one.

**payoutStatus** `string`

Where the bank transfer stands while one is in flight.

**updatedAt** `string`

When the transfer last changed, as an ISO 8601 timestamp.

Updates carry no bank details and nothing about who sent the transfer. To match
a transfer to one of your users, look its address up with
[`GET /pub/v2/bank-account`](https://docs.paj.cash/api-reference/search-bank-account).

### Stages

These follow the steps in
[what happens after a deposit](https://docs.paj.cash/concepts/bank-account-addresses.md#what-happens-after-a-deposit):

| Stage | Meaning |
| - | - |
| `received` | Paj has seen the deposit and queued it. |
| `processing` | It is being swept into the treasury, swapped or priced, or paid out to the bank. Several updates may arrive in this stage, one per step. |
| `completed` | The naira payout went through. This is final, and no more updates follow. |
| `error` | A step failed. **This is not final.** Failed transfers are retried, and a retry moves the transfer back to `processing`. |

Treat only `completed` as the end of a transfer. If a transfer stays in `error`,
contact Paj with its signature.

> [!NOTE]
>
> A transfer worth less than 0.40 USDC is too small to pay out and is never
> picked up, so its subscription gets no updates.

## Staying connected

Subscriptions belong to the connection. When a connection drops, its
subscriptions go with it, and Socket.IO reconnects with a fresh connection and
none of them. Subscribe again on every `connect`, not just the first:

```javascript theme={null}
const watching = new Set();

function watch(signature) {
  watching.add(signature);
  if (socket.connected) socket.emit('subscribe', { signature }, onAck);
}

socket.on('connect', () => {
  for (const signature of watching) {
    socket.emit('subscribe', { signature }, onAck);
  }
});

socket.on('TX_POOL_UPDATE', (update) => {
  if (update.stage === 'completed') {
    watching.delete(update.signature);
    socket.emit('unsubscribe', { signature: update.signature });
  }
});
```

Updates sent while you were disconnected are not replayed. The acknowledgement
of each new subscription carries the current state, so after reconnecting you
are back in step without anything else.


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