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

# Authentication

> Stocks uses your Daya API key with Stocks scopes

<Warning>
  **Live only for now.** Stocks does not have a sandbox yet — every request runs against the live environment with real balances and real money. Sandbox keys (`sk_sandbox_...`) are not accepted, and the dashboard's sandbox mode shows a notice instead of Stocks data. Sandbox support is on the way.
</Warning>

## The shared key model

Stocks is an extension of the Daya API, so it does **not** have its own key-issuance flow. You authenticate Stocks requests with the **same Daya API key** you use for the rest of the Daya API — the same key, the same header, the same dashboard.

<Info>
  Issue and manage your Daya API keys in the [Daya dashboard](https://dashboard.daya.co). When you create or edit a key, grant it the Stocks scopes your integration needs. There is no separate Stocks key to request.
</Info>

Send the key in the `X-API-Key` header on every request:

```text theme={"dark"}
X-API-Key: YOUR_DAYA_API_KEY
```

## Stocks scopes

A Daya API key carries scopes. To call Stocks endpoints, the key must include the matching Stocks scope:

| Scope             | Grants                                                               |
| ----------------- | -------------------------------------------------------------------- |
| `stocks:read`     | Assets, prices, balance, portfolio, and transactions                 |
| `stocks:trade`    | Request quotes (`/quote`, `/fx/quotes`) and place orders (`/orders`) |
| `stocks:write`    | Manage payout bank accounts                                          |
| `stocks:withdraw` | Create fiat withdrawals                                              |

<Warning>
  `stocks:withdraw` authorizes fund movement off the platform. Only attach it to keys stored in trusted server-side systems.
</Warning>

## Making an authenticated request

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl --request GET \
    --url https://api.daya.co/stocks/v1/balance \
    --header 'X-API-Key: YOUR_DAYA_API_KEY'
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch('https://api.daya.co/stocks/v1/balance', {
    headers: { 'X-API-Key': 'YOUR_DAYA_API_KEY' }
  });

  const result = await response.json();
  console.log(result.data);
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.get(
      'https://api.daya.co/stocks/v1/balance',
      headers={'X-API-Key': 'YOUR_DAYA_API_KEY'}
  )
  print(response.json()['data'])
  ```
</CodeGroup>

## Error responses

Stocks uses the standard Daya response envelope: `{ success, message?, data?, error?, timestamp }`.

### 401 Unauthorized

Missing or invalid API key:

```json theme={"dark"}
{
  "success": false,
  "message": "Unauthorized",
  "error": { "code": "API_KEY_INVALID", "message": "Invalid or missing API key" },
  "timestamp": "2026-01-15T10:30:00Z"
}
```

### 403 Forbidden

The key is valid but is missing the required Stocks scope:

```json theme={"dark"}
{
  "success": false,
  "message": "Forbidden",
  "error": { "code": "API_KEY_INVALID_SCOPE", "message": "Insufficient scope for this operation" },
  "timestamp": "2026-01-15T10:30:00Z"
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/stocks/quickstart">
    Your first authenticated call, end to end.
  </Card>

  <Card title="Concepts" icon="book" href="/stocks/concepts">
    Balances, quotes, orders, and withdrawals.
  </Card>
</CardGroup>