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

# Quickstart

> Quote and place your first Stocks order

## Overview

This guide walks a full quote-to-execute flow: find an asset, quote a buy in USD, then accept the quote to place an order. Every call uses your Daya API key in the `X-API-Key` header.

<Info>
  **Prerequisites:** a Daya API key with `stocks:read` and `stocks:trade` scopes. Issue keys in the [Daya dashboard](https://dashboard.daya.co). See [Authentication](/stocks/authentication).
</Info>

## Step 1: Find an asset

Search and sort the catalog. The `sort` query ranks results (for example, trending or top movers).

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl --request GET \
    --url 'https://api.daya.co/stocks/v1/assets?q=apple&sort=trending&limit=1' \
    --header 'X-API-Key: YOUR_DAYA_API_KEY'
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch(
    'https://api.daya.co/stocks/v1/assets?q=apple&sort=trending&limit=1',
    { headers: { 'X-API-Key': 'YOUR_DAYA_API_KEY' } }
  );
  console.log((await res.json()).data);
  ```

  ```python Python theme={"dark"}
  import requests
  res = requests.get(
      'https://api.daya.co/stocks/v1/assets',
      params={'q': 'apple', 'sort': 'trending', 'limit': 1},
      headers={'X-API-Key': 'YOUR_DAYA_API_KEY'}
  )
  print(res.json()['data'])
  ```
</CodeGroup>

**Response:**

```json theme={"dark"}
{
  "success": true,
  "message": "Assets retrieved",
  "data": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "price_usd": "231.40",
      "change_24h_pct": "1.24",
      "market_status": "open",
      "is_market_open": true,
      "min_order_usd": "1.00",
      "max_order_usd": "50000.00"
    }
  ],
  "timestamp": "2026-01-15T10:30:00Z"
}
```

## Step 2: Request a quote

Quote a \$100 buy of `AAPL`. The response is a short-lived quote with an `id` and an `expires_at`; the fee and total are already computed.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl --request POST \
    --url https://api.daya.co/stocks/v1/quote \
    --header 'X-API-Key: YOUR_DAYA_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "symbol": "AAPL", "side": "buy", "amount_usd": "100.00" }'
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch('https://api.daya.co/stocks/v1/quote', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_DAYA_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ symbol: 'AAPL', side: 'buy', amount_usd: '100.00' })
  });
  const quote = (await res.json()).data;
  console.log(quote.id, quote.total_usd, quote.expires_at);
  ```

  ```python Python theme={"dark"}
  import requests
  res = requests.post(
      'https://api.daya.co/stocks/v1/quote',
      headers={'X-API-Key': 'YOUR_DAYA_API_KEY'},
      json={'symbol': 'AAPL', 'side': 'buy', 'amount_usd': '100.00'}
  )
  quote = res.json()['data']
  print(quote['id'], quote['total_usd'], quote['expires_at'])
  ```
</CodeGroup>

**Response:**

```json theme={"dark"}
{
  "success": true,
  "message": "Quote issued",
  "data": {
    "id": "qt_7b3f1a9c...",
    "symbol": "AAPL",
    "name": "Apple Inc.",
    "side": "buy",
    "price_usd": "231.40",
    "quantity": "0.43215000",
    "notional_usd": "100.00",
    "fee_usd": "0.00",
    "total_usd": "100.00",
    "expires_at": "2026-01-15T10:30:15Z"
  },
  "timestamp": "2026-01-15T10:30:00Z"
}
```

## Step 3: Accept the quote and place the order

Reference the quote `id` to execute. Create and save one `Idempotency-Key` for this logical order before sending it. Reuse the same key for every retry.

<CodeGroup>
  ```bash cURL theme={"dark"}
  IDEMPOTENCY_KEY='4a7f6b2e-1c3d-4e5f-8a9b-0c1d2e3f4a5b'

  curl --request POST \
    --url https://api.daya.co/stocks/v1/orders \
    --header 'X-API-Key: YOUR_DAYA_API_KEY' \
    --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
    --header 'Content-Type: application/json' \
    --data '{ "quote_id": "qt_7b3f1a9c..." }'
  ```

  ```javascript JavaScript theme={"dark"}
  const idempotencyKey = crypto.randomUUID();
  // Persist this key with the logical order before the first request.
  const res = await fetch('https://api.daya.co/stocks/v1/orders', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_DAYA_API_KEY',
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ quote_id: 'qt_7b3f1a9c...' })
  });
  console.log((await res.json()).data);
  ```

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

  idempotency_key = str(uuid.uuid4())
  # Persist this key with the logical order before the first request.
  res = requests.post(
      'https://api.daya.co/stocks/v1/orders',
      headers={
          'X-API-Key': 'YOUR_DAYA_API_KEY',
          'Idempotency-Key': idempotency_key
      },
      json={'quote_id': 'qt_7b3f1a9c...'}
  )
  print(res.json()['data'])
  ```
</CodeGroup>

**Response:**

```json theme={"dark"}
{
  "success": true,
  "message": "Order placed",
  "data": {
    "id": "ord_3c5e7a1b",
    "symbol": "AAPL",
    "side": "buy",
    "quantity": "0.43215000",
    "notional_usd": "100.00",
    "fee_usd": "0.00",
    "status": "pending",
    "created_at": "2026-01-15T10:30:05Z"
  },
  "timestamp": "2026-01-15T10:30:05Z"
}
```

<Info>
  Order placement is asynchronous. Do not allocate shares from the initial `pending` response. Wait for an `order.filled` or `order.failed` webhook, or poll `GET /orders/{id}` for a terminal status.
</Info>

<Info>
  Quotes expire. If the quote `id` is no longer valid, request a fresh quote and retry with a new logical-order idempotency key.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Concepts" icon="book" href="/stocks/concepts">
    How quotes, orders, and withdrawals fit together.
  </Card>

  <Card title="API Reference" icon="code" href="/stocks/api-reference/overview">
    Every Stocks endpoint with schemas and examples.
  </Card>
</CardGroup>