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

# Concepts

> Balances, quotes, orders, transactions, and withdrawals in Coins

Coins adds a small set of primitives on top of the [Daya API](/index). Shared primitives (customers, funding, webhooks) live there — this page covers only the Coins delta.

## Balances

`GET /balance` returns your USD cash position — `available`, `held`, and `total`. `held` currently returns `"0"`, so `total` equals `available`. `GET /wallet/portfolio` breaks the position into per-asset holdings with 24h stats.

<Note>
  Coins balances are separate from Stocks and the Business API — value in one product is not automatically available in another.
</Note>

## Trade: quote → order

Trading a coins asset is quote-driven. `POST /quote` prices a conversion between two assets; `POST /orders` executes it.

<Steps>
  <Step title="Quote">
    `POST /quote` with `input_asset`, `output_asset`, and exactly one of `input_amount` / `output_amount`. Returns an `id`, a `rate`, and an `expires_at`.
  </Step>

  <Step title="Execute">
    `POST /orders` with the quote `id` as `quote_id`. Save one `Idempotency-Key` for the logical order and reuse it for every retry.
  </Step>
</Steps>

Quote amounts are shown fee-inclusive so you can render real numbers; the taker fee settles as a separate component at execution.

## Cash out: FX quote → withdrawal

A fiat withdrawal converts your USD balance to NGN, so it needs a **currency** quote — separate from the trade quote above. `POST /fx/quotes` locks a **USD→NGN** rate; `POST /fiat-withdrawals` pays it out to a bank account.

<Steps>
  <Step title="FX quote">
    `POST /fx/quotes` with `amount_usd`. Returns an `id`, the USD→NGN `rate`, and an `expires_at`.
  </Step>

  <Step title="Withdraw">
    `POST /fiat-withdrawals` with the `bank_account_id` and the FX quote `id` as `quote_id`.
  </Step>
</Steps>

<Warning>
  Quotes expire after a few seconds. An expired quote returns `410 Gone`; a reused quote returns `409 Conflict`. Request a fresh quote and retry — the price you show a customer is the price they get.
</Warning>

<CodeGroup>
  ```bash Trade quote theme={"dark"}
  curl -X POST https://api.daya.co/coins/v1/quote \
    -H "X-API-Key: $DAYA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "input_asset": "USD", "output_asset": "BTC", "input_amount": "100"}'
  ```

  ```bash FX quote (cash out) theme={"dark"}
  curl -X POST https://api.daya.co/coins/v1/fx/quotes \
    -H "X-API-Key: $DAYA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "amount_usd": "100" }'
  ```
</CodeGroup>

## Orders

`POST /orders` executes a trade `quote_id`. List them with `GET /orders`, fetch one with `GET /orders/{id}`.

| Field    | Values                          |
| -------- | ------------------------------- |
| `side`   | `buy` · `sell`                  |
| `status` | `pending` · `filled` · `failed` |

Each order also carries executed amounts (`base_amount`, `quote_amount`), an `executed_price`, and a `fee` (with its `fee_asset`).

<Info>
  The execution venue is never part of the contract — you request the economic result, and Daya routes and settles.
</Info>

## Transactions

`GET /transactions` is a cursor-paginated statement of money movements — deposits and withdrawals. Trades are not activity here; read them under [Orders](#orders). Filter with `?direction=in` (deposits) or `?direction=out` (withdrawals), optionally filter by `asset`, and pass the returned `next_cursor` to page.

A movement is described by two orthogonal fields — the rail (`method`) and which way value moved (`direction`):

| Field       | Values                                            |
| ----------- | ------------------------------------------------- |
| `method`    | `onchain` · `bank_transfer`                       |
| `direction` | `in` · `out`                                      |
| `status`    | `pending` · `processing` · `completed` · `failed` |

So `bank_transfer` + `in` is a fiat deposit; `onchain` + `out` is a crypto withdrawal. Each entry also carries `id`, `asset`, `amount` (native), `amount_usd`, `created_at`, and `completed_at`.

```json theme={"dark"}
{
  "success": true,
  "message": "Transactions retrieved",
  "data": {
    "transactions": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "method": "bank_transfer",
        "direction": "out",
        "status": "completed",
        "asset": "USD",
        "amount": "250.00",
        "amount_usd": "250.00",
        "created_at": "2026-01-15T10:30:00Z",
        "completed_at": "2026-01-15T10:31:40Z"
      }
    ],
    "next_cursor": "eyJvIjoyMH0"
  },
  "timestamp": "2026-01-15T10:31:45Z"
}
```

## Withdrawals

Coins supports two rails:

| Rail       | Flow                                                                                                                                                               |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Crypto** | `GET /crypto-withdrawals/assets` (options) → `/crypto-withdrawals/addresses` (saved addresses) → `/crypto-withdrawals/fee` (estimate) → `POST /crypto-withdrawals` |
| **Fiat**   | `POST /fx/quotes` (USD→NGN rate) → `/bank-accounts` (payout accounts) → `POST /fiat-withdrawals`                                                                   |

Both rails report a `status`: `pending` · `processing` · `completed` · `failed`.

| Action                                 | Scope            |
| -------------------------------------- | ---------------- |
| Create a withdrawal                    | `coins:withdraw` |
| Manage saved addresses / bank accounts | `coins:write`    |

## Response envelope

Every Coins response uses the standard Daya envelope:

<CodeGroup>
  ```json Success theme={"dark"}
  { "success": true, "message": "...", "data": { }, "timestamp": "2026-01-15T10:30:00Z" }
  ```

  ```json Error theme={"dark"}
  { "success": false, "error": { "code": "ERR_CODE", "message": "..." }, "timestamp": "2026-01-15T10:30:00Z" }
  ```
</CodeGroup>