# Request a Pool Withdrawal

Pay a customer out of the omnibus: the amount leaves their claim at once, and Aurea sends it from your pool.

> Note: **Coming with the omnibus processing** ([Feature Availability](https://docs.aureahub.com/docs/feature-availability.md)). Until then a request written right answers `503` `OMNIBUS_JOB_OFF` (`Pool withdrawals are switched off on this platform`): nothing is debited or queued. A request written wrong still answers `400`.

## Overview

- **The body**: `accountId` — the customer's collection account on this network (`400` `OMNIBUS_ACCOUNT_NOT_COLLECTION` otherwise) —; `chainId`, a number; `asset` — `native` or the token's address in any case, an omnibus asset of that chain, one with a sweep policy (`400` `OMNIBUS_ASSET_UNKNOWN` otherwise) —; `amount`, above 0, in the asset's smallest unit as text; `destination`, an EVM address — not the zero address (`400` `OMNIBUS_DESTINATION_INVALID`), not a wallet of the omnibus (`400` `OMNIBUS_DESTINATION_INTERNAL`) —; `externalId`, your own id for it.
- **Debited at once**: the amount leaves the customer's claim — never more than the claim: `409` `OMNIBUS_INSUFFICIENT_CLAIM`, the claim in `details.claim`. `202` with the withdrawal, `status` `queued`.
- **Sent from the pool**: at the next pass, from the pool account the pool's rule picks among those that can pay it, through your signing rules, and followed to its receipt — follow it with [Get a Transfer](https://docs.aureahub.com/docs/structures-transfer-get.md). While none can pay it, it waits (`reason` `NO_POOL_WALLET`). If it fails, its amount goes back to the claim. [Account Structures](https://docs.aureahub.com/docs/guide-account-structures.md) › Pool Withdrawals.
- **Idempotent on `externalId`** — 1 to 128 of `A–Z a–z 0–9 _ . : -`, unique among your tenant's withdrawals on both networks. The same request again, on the same network with the same body, answers `200` with the same withdrawal as it is now — nothing is debited twice. Anything else under that id: `409` `OMNIBUS_EXTERNAL_ID_TAKEN`, with the withdrawal's id in `details.transferId`. The route takes no `Idempotency-Key`: `externalId` is the key.
- A segregated network: `409` `STRUCTURE_NOT_OMNIBUS`. A body written wrong, or with a field it does not have: `400` `STRUCTURE_REQUEST_INVALID`.
- **For your signers**: `owner`, `tenantadmin` and `signer` — never the `non_signing_admin` —, on their own tenant, with an access token. Its operation, once signed, is a `TRANSFER` with `origin` `omnibus.withdrawal` and the caller as `userId`. Written to your audit trail [Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md), as `omnibus.withdrawal_requested` (category `money`).

## Endpoint

### `POST /v1/structures/{network}/withdrawals`

Authentication: bearer token required.

Debits a customer's claim and queues the payout from the pool.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `network` | string | yes | `mainnet` or `testnet` |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | string (uuid) | yes | The customer's collection account |
| `chainId` | integer | yes | The chain, e.g. `8453` (Base) |
| `asset` | string | yes | `native`, or the token's contract address: an omnibus asset of the chain |
| `amount` | string | yes | In the asset's smallest unit, as text; above 0 |
| `destination` | string | yes | The EVM address it is paid to |
| `externalId` | string | yes | Your own id: 1–128 of `A–Z a–z 0–9 _ . : -` |

**Responses**

`202` Queued

```json
{
  "id": "7bd81096-6c7e-486b-b1c6-5f8ddd22bd20",
  "network": "mainnet",
  "kind": "withdrawal",
  "status": "queued",
  "reason": null,
  "chainId": 8453,
  "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "amount": "40000000",
  "accountId": "f22d2b25-338e-444c-93ef-71693565f346",
  "sourceAccountId": null,
  "walletId": null,
  "fromAddress": null,
  "toAddress": "0xc96c76854540b6a68cc7ff444657adca563a4e74",
  "toAccountId": null,
  "txHash": null,
  "nonce": null,
  "blockNumber": null,
  "fee": null,
  "operationId": null,
  "externalId": "payout-2026-10-14-0043",
  "createdAt": "2026-10-14T10:05:31.642Z",
  "updatedAt": "2026-10-14T10:05:31.642Z",
  "sentAt": null,
  "finishedAt": null
}
```

`200` Same request again

```json
{
  "id": "7bd81096-6c7e-486b-b1c6-5f8ddd22bd20",
  "network": "mainnet",
  "kind": "withdrawal",
  "status": "sent",
  "reason": null,
  "chainId": 8453,
  "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "amount": "40000000",
  "accountId": "f22d2b25-338e-444c-93ef-71693565f346",
  "sourceAccountId": "a9dcb8c6-9bee-4900-b792-cd01bd77820b",
  "walletId": "9ef4730c-d384-4359-b0ed-820e2297b0f9",
  "fromAddress": "0x79c7756b0b77d992feadf0d152503c40de259750",
  "toAddress": "0xc96c76854540b6a68cc7ff444657adca563a4e74",
  "toAccountId": null,
  "txHash": "0xfa2f28593f46c4dc65b1191f0864252cd04a4c4eb1f85a40ee225cb8f390a862",
  "nonce": 18,
  "blockNumber": null,
  "fee": null,
  "operationId": "9d6e6d08-f0bd-4ad8-a5f2-7cff654c614a",
  "externalId": "payout-2026-10-14-0043",
  "createdAt": "2026-10-14T10:05:31.642Z",
  "updatedAt": "2026-10-14T10:06:33.019Z",
  "sentAt": "2026-10-14T10:06:33.019Z",
  "finishedAt": null
}
```

`503` Not enabled

```json
{
  "statusCode": 503,
  "error": "ServiceUnavailableError",
  "message": "Pool withdrawals are switched off on this platform",
  "details": { "code": "OMNIBUS_JOB_OFF" }
}
```

`409` Above the claim

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "The customer's claim on the omnibus is smaller than the amount",
  "details": { "code": "OMNIBUS_INSUFFICIENT_CLAIM", "claim": "35500000" }
}
```

`409` externalId taken

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "Another withdrawal has this externalId",
  "details": {
    "code": "OMNIBUS_EXTERNAL_ID_TAKEN",
    "transferId": "7bd81096-6c7e-486b-b1c6-5f8ddd22bd20"
  }
}
```

`400` Not a collection account

```json
{
  "statusCode": 400,
  "error": "BadRequestError",
  "message": "The account is no collection account of the omnibus",
  "details": { "code": "OMNIBUS_ACCOUNT_NOT_COLLECTION" }
}
```

`400` Invalid

```json
{
  "statusCode": 400,
  "error": "BadRequestError",
  "message": "Invalid request",
  "details": {
    "code": "STRUCTURE_REQUEST_INVALID",
    "errors": [
      "chainId: Expected number, received string",
      "amount: greater than 0",
      "externalId: Invalid"
    ]
  }
}
```

**Example request**

```bash
curl -X POST https://api.aureahub.com/v1/structures/mainnet/withdrawals \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "f22d2b25-338e-444c-93ef-71693565f346",
    "chainId": 8453,
    "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "amount": "40000000",
    "destination": "0xc96c76854540b6a68cc7ff444657adca563a4e74",
    "externalId": "payout-2026-10-14-0043"
  }'
```

---

Web version: https://docs.aureahub.com/#structures-withdrawal-create