> ## 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 Stocks

Stocks 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 Stocks delta.

## Balances

`GET /balance` returns your USD cash position — `available`, `held`, and `total`. `GET /wallet/portfolio` breaks holdings down per asset.

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

## Assets & market hours

`GET /assets` is one endpoint that searches, filters, ranks, and paginates the catalog:

| Param      | Purpose                                   |
| ---------- | ----------------------------------------- |
| `q`        | Search by name or symbol                  |
| `sort`     | `popular` · `trending` · `top_performing` |
| `category` | Filter by segment                         |
| `limit`    | Page size                                 |

Each asset reports `price_usd`, `market_status`, `is_market_open`, off-hours eligibility, and `min_order_usd` / `max_order_usd` — so you can validate an order **before** you quote it. `market_status` is one of `open` · `regular` · `premarket` · `postmarket` · `overnight` · `closed` · `paused` · `off_hours`.

## Quote → execute

Trading is quote-driven — the price you show a customer is the price they get.

<Steps>
  <Step title="Request a quote">
    `POST /quote` with a `symbol`, a `side` (`buy`/`sell`), and either `amount_usd` or `quantity`. Returns an `id`, a `price_usd`, computed `fee_usd` / `total_usd`, and an `expires_at`.
  </Step>

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

<Warning>
  Quotes expire (`expires_at`). If a quote `id` is no longer valid, request a fresh quote and retry.
</Warning>

<CodeGroup>
  ```bash Quote theme={"dark"}
  curl -X POST https://api.daya.co/stocks/v1/quote \
    -H "X-API-Key: $DAYA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "symbol": "AAPL", "side": "buy", "amount_usd": "100" }'
  ```

  ```bash Execute theme={"dark"}
  curl -X POST https://api.daya.co/stocks/v1/orders \
    -H "X-API-Key: $DAYA_API_KEY" \
    -H "Idempotency-Key: <stable-uuid>" \
    -H "Content-Type: application/json" \
    -d '{ "quote_id": "<id>" }'
  ```
</CodeGroup>

## Orders

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

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

Each order also carries `quantity`, `notional_usd`, and `fee_usd`.

## 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 `?method=onchain|bank_transfer`.

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` + `in` is a crypto deposit. Each entry also carries `id`, `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",
        "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

Cash out over the fiat rail:

<Steps>
  <Step title="Add a payout account">
    List banks (`GET /fiat-withdrawals/banks`), verify the account (`POST /fiat-withdrawals/resolve-account`), then save it (`POST /fiat-withdrawals/accounts`).
  </Step>

  <Step title="Lock the rate">
    `POST /fx/quotes` for the USD→NGN conversion — returns an `id`.
  </Step>

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

| Action               | Scope             |
| -------------------- | ----------------- |
| Manage bank accounts | `stocks:write`    |
| Create a withdrawal  | `stocks:withdraw` |

## Response envelope

Every Stocks 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>