# Fee sinks

> Inspect the rotating fee-receiver pool and trigger sweeps, rotations and drains.

Fee sinks are rotating addresses that receive Proxima's fees on each chain before they are drained to the treasury. A sink moves from `funding` to `active`, then `draining` and `retired`.

These endpoints serve the admin *Sinks* page. Sweeps and rotations normally run on a schedule; the trigger endpoints start a run now.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `GET /admin/sinks`: List sinks
- `POST /admin/sinks/run-sweep`: Run a fee sweep
- `POST /admin/sinks/run-rotation`: Run a sink rotation
- `POST /admin/sinks/{sink_id}/close`: Close a sink

## The Sink object

A fee-receiver address with its live balances. No secrets are returned.

- `id` (integer): Sink id.
- `chain_id` (string): Chain id.
- `asset` (enum): Asset the sink collects. Possible values: `native`, `usdc`, `usd1`.
- `address` (string): Sink address.
- `status` (enum): Lifecycle status. Possible values: `funding`, `active`, `draining`, `retired`.
- `total_received_usd` (integer): Total received, in micro-USD.
- `husher_order_id` (string | null): Id of the drain order.
- `drain_token` (string | null): Token the drain delivers.
- `drain_network` (string | null): Network the drain delivers on.
- `opened_at` (integer | null): Creation time, Unix seconds.
- `activated_at` (integer | null): Activation time, Unix seconds.
- `retired_at` (integer | null): Retirement time, Unix seconds.
- `native_balance` (string): Live native balance, in lamports or wei, as an integer string.
- `token_balance` (string): Live asset balance in base units, as an integer string.

```json
{
  "id": 42,
  "chain_id": "sol",
  "asset": "usdc",
  "address": "Fgi2HMYCFt7Hu4ZR7fmiHNxQQvqVDgPx8WUz23zE33Xc",
  "status": "active",
  "total_received_usd": 1840000000,
  "husher_order_id": null,
  "drain_token": null,
  "drain_network": null,
  "opened_at": 1791900000,
  "activated_at": 1791900120,
  "retired_at": null,
  "native_balance": "2039280",
  "token_balance": "1840000000"
}
```

### List sinks

`GET /admin/sinks`

Returns one chain's sinks with live on-chain balances, newest first. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Query parameters

- `chain` (enum, optional, default "sol"): Chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`.
- `status` (enum, optional): Filters on status. Use `retired` to see closed sinks. Possible values: `funding`, `active`, `draining`, `retired`.
- `asset` (enum, optional): Filters on asset. Possible values: `native`, `usdc`, `usd1`.

#### Returns 200 OK

- `sinks` (array<object>): Sinks. See [Sink](#object-sink).

#### Example request

```bash
curl "https://api-mig.proxima.tools/admin/sinks" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "sinks": [
    {
      "id": 42,
      "chain_id": "sol",
      "asset": "usdc",
      "address": "Fgi2HMYCFt7Hu4ZR7fmiHNxQQvqVDgPx8WUz23zE33Xc",
      "status": "active",
      "total_received_usd": 1840000000,
      "husher_order_id": null,
      "drain_token": null,
      "drain_network": null,
      "opened_at": 1791900000,
      "activated_at": 1791900120,
      "retired_at": null,
      "native_balance": "2039280",
      "token_balance": "1840000000"
    }
  ]
}
```

### Run a fee sweep

`POST /admin/sinks/run-sweep`

Starts a fee sweep on a chain now. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A sweep already running makes the new one skip, and a later run only collects what is still pending.

A sweep collects fees into the sinks and pays referrers. It runs in the background: the response only confirms it started, and failures are not reported back.

> Moves funds: fees are collected and referral payouts are sent.

#### Query parameters

- `chain` (enum, optional, default "sol"): Chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`.

#### Returns 200 OK

- `ok` (boolean): `true` when accepted.
- `triggered` (string): Job started: `fee_sweep` or `sink_rotation`.
- `chain` (string): The `chain` query value, `sol` when omitted.

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/sinks/run-sweep" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "triggered": "fee_sweep",
  "chain": "sol"
}
```

### Run a sink rotation

`POST /admin/sinks/run-rotation`

Starts a sink rotation on a chain now. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A rotation already running makes the new one skip, and a later run only acts on sinks that still need it.

A rotation maintains the sink pool and drains sinks. It runs in the background: the response only confirms it started.

> Moves funds: sinks may be drained.

#### Query parameters

- `chain` (enum, optional, default "sol"): Chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`.

#### Returns 200 OK

- `ok` (boolean): `true` when accepted.
- `triggered` (string): Job started: `fee_sweep` or `sink_rotation`.
- `chain` (string): The `chain` query value, `sol` when omitted.

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/sinks/run-rotation" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "triggered": "sink_rotation",
  "chain": "sol"
}
```

### Close a sink

`POST /admin/sinks/{sink_id}/close`

Drains an active sink to the treasury and retires it. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. A lost call may have started the drain. Read the sink with [List sinks](/reference/admin-sinks/#list-sinks): `draining` or `retired` means it did.

The sink moves to `draining` at once and to `retired` once the drain settles. The sink's own chain is used.

> Moves funds and cannot be undone: the sink stops receiving fees.

#### Path parameters

- `sink_id` (integer, required): Sink id.

#### Returns 200 OK

- `ok` (boolean): `true` when accepted.
- `message` (string): Outcome, such as `drain initiated for usdc sink 42`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 422 | `unprocessable` | `sink not found` | No sink has this id. | Use a sink id returned by [List sinks](/reference/admin-sinks/#list-sinks). |
| 422 | `unprocessable` | `rotation in progress, retry shortly` | A sink rotation is running and holds the sinks. | Retry in a few seconds. |
| 422 | `unprocessable` | `sink <sink_id> is '<status>'; only active sinks can be drained` | The sink is not `active`: it is still funding, already draining, or retired. | Check the sink's `status` with [List sinks](/reference/admin-sinks/#list-sinks); only an `active` sink can be closed. |
| 422 | `unprocessable` | `<reason>` | The drain could not start, for example `husher not configured`. The message is the reason, and the sink stays `active`. | Fix the cause in the message, then retry. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/admin/sinks/{sink_id}/close" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "message": "drain initiated for usdc sink 42"
}
```
