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

# Partner Integration

> Launch Stocks for your customers with a clear funding, order, and reconciliation flow

## What you are integrating

Stocks lets your business offer supported instrument discovery, quote-based trading, portfolio views, and fiat withdrawals through the Daya API. The catalog can include stocks, ETFs, metals, and pre-IPO instruments. Daya keeps the aggregate Stocks cash balance, positions, and orders for your business. Your application keeps each customer's cash and position allocation.

<Warning>
  Stocks cash is separate from Coins and Business balances. A customer with funds in another Daya product cannot spend them in Stocks until a separate, supported funding operation has completed. See the [integration model](/stocks/integration-model).
</Warning>

## Start here

| Step                     | What to do                                                                                                                                                                                                          | Where to go                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| 1. Get access            | Create a Daya API key with `stocks:read` and `stocks:trade`. Add `stocks:write` or `stocks:withdraw` only when needed. Keep the key on your server.                                                                 | [Authentication](/stocks/authentication)               |
| 2. Verify the account    | Complete KYC on the Stocks account tied to the API key. Sign in with the email used to create that account.                                                                                                         | See [Account KYC](#account-kyc) below.                 |
| 3. Plan your ledger      | Give each customer an internal account and operation ID. Map Daya orders, positions, deposits, and withdrawals back to it.                                                                                          | [Integration model](/stocks/integration-model)         |
| 4. Fund Stocks           | Read available fiat and crypto deposit options. Show a bank account only when `account.status` is `active`. Use only returned crypto instructions and supported minimums.                                           | [Stocks API reference](/stocks/api-reference/overview) |
| 5. Check cash            | Read `GET /stocks/v1/balance` and wait for the deposit to complete before allowing a buy.                                                                                                                           | [Quickstart](/stocks/quickstart)                       |
| 6. Discover and quote    | Search `GET /stocks/v1/assets`, then fetch `GET /stocks/v1/assets/{symbol}` before display. Check ownership disclosures, instrument `status`, order side, market status, and limits before `POST /stocks/v1/quote`. | [Concepts](/stocks/concepts)                           |
| 7. Place an order        | Send the quote `id` as `quote_id` to `POST /stocks/v1/orders` before expiry. Keep one `Idempotency-Key` for the logical order.                                                                                      | [Quickstart](/stocks/quickstart)                       |
| 8. Confirm and reconcile | Wait for the final order event or poll the order. Post the customer position once and reconcile it with the Stocks portfolio.                                                                                       | [Webhooks](/stocks/webhooks/overview)                  |

<Info>
  The current [Stocks authentication guide](/stocks/authentication) says Stocks is live-only. Do not use a sandbox key or send test payments to a live deposit account.
</Info>

## Verified public contract

The Stocks service mounts these actions under `https://api.daya.co/stocks/v1`. Scopes are independent, so grant every scope a server process actually needs.

| Action                                                                                                   | Representative routes                                             | Required scope                      |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------- |
| Read assets, prices, balances, portfolio, orders, transactions, deposit options, and saved bank accounts | `GET /assets`, `GET /balance`, `GET /orders`, `GET /transactions` | `stocks:read`                       |
| Quote and place stock orders                                                                             | `POST /quote`, `POST /orders`                                     | `stocks:trade`                      |
| Resolve and manage payout bank accounts                                                                  | Bank-account resolve, create, and delete routes                   | `stocks:write`                      |
| Create a fiat withdrawal                                                                                 | `POST /fiat-withdrawals`                                          | `stocks:withdraw`                   |
| Request a USD-to-NGN withdrawal quote                                                                    | `POST /fx/quotes`                                                 | `stocks:trade` or `stocks:withdraw` |

Webhook destinations are managed in the Daya Dashboard; the Stocks API-key surface does not expose webhook-configuration routes.

## Account KYC

The API key acts as one Daya Stocks account. Complete KYC for that same account before funding or trading. Sign in to Stocks with the email used to create the account associated with the key. KYC completed on a different email or account will not unlock this one. Daya applies verification to the account identity behind the key, not to an email supplied in an order request.

Basic verification (Tier 1) unlocks funding and trading when the account is otherwise eligible. Withdrawals need full withdrawal verification (Tier 2) and an enabled withdrawal capability. Read-only API calls can be available before Tier 1; this does not mean the account can buy stocks or cash out. Complete KYC through the Stocks account onboarding flow, not by sending identity documents to these public trading endpoints. Confirm the account's verification state with Daya before launch.

The public Stocks order does not carry an end-customer ID. This account-level KYC check is not a KYC check for each customer in your product. Keep your own customer identity and compliance process for the users whose funds and positions you allocate in your ledger.

## Funding and customer ownership

Use `GET /stocks/v1/fiat-deposits/options` to learn which bank-transfer instructions are available for the Stocks account. Display bank details only when the returned `account.status` is `active`. Do not accept a transfer to an account with `status: disabled`. Use `GET /stocks/v1/crypto-deposits/options` for supported crypto instructions. A deposit into Business or Coins does not automatically become Stocks cash. Wait for `deposit.completed`, then check the transaction and cash balance before accepting a customer buy.

The public Stocks order request has no customer identifier. Your product must authorize the end user, record the customer-to-order mapping, and keep a customer-level subledger. Deposit options belong to the Stocks account; do not infer a customer from an account-level address alone. Attribute and reconcile the deposit before you credit that customer. Use the Daya portfolio for aggregate reconciliation, not as a ready-made portfolio for each customer.

## Market sessions and orders

Stocks orders use USD notional or quantity. Asset responses expose instrument `status` separately from `market_status`, open-hours information, and order limits. Check all of them before quoting. An open market does not make a `disabled`, `paused`, `unavailable`, `migrated`, or `delisted` instrument tradable. `closing_only` permits only eligible sells, not buys. Do not promise a trade will execute just because a ticker appears in the catalog.

Quotes expire. Request a new quote when one expires. A successful order-create response is not a completed purchase. Use `order.filled` or `order.failed`, or poll `GET /stocks/v1/orders/{id}`. Save one `Idempotency-Key` per logical order and reuse it after a network timeout. Never debit the customer twice for one Daya order.

Fetch `GET /stocks/v1/assets/{symbol}` before you display an instrument. The asset-detail response contains the ownership fields that the asset catalog does not return. Use the detail response's `category` when you describe the instrument. It can be `stock`, `etf`, `metal`, or `pre_ipo`. Also preserve `economic_exposure_only`, `legal_form`, `ownership_rights`, `voting_rights`, and `shareholder_rights_disclosure` in your product disclosures. Do not describe economic exposure as direct share ownership. Stocks-product instruments are not Robinhood Chain tokens in Coins. Do not mix their catalogs, order IDs, or customer ledgers.

## Cash out

The fiat cash-out flow uses `POST /stocks/v1/fx/quotes` for a USD-to-NGN quote, a saved bank account, and `POST /stocks/v1/fiat-withdrawals`. Read the [withdrawal concepts](/stocks/concepts) and endpoint reference for required fields. The key needs `stocks:withdraw`; managing saved accounts needs `stocks:write`.

Create and retain one `Idempotency-Key` for each logical withdrawal. If the withdrawal request times out before returning an ID, replay the exact request with the same key. Do not generate a new key for that retry.

Withdrawal creation can return `503 WITHDRAWALS_DISABLED` when that capability is off. Do not assume an enabled read endpoint means money-out is enabled. Do not retry a disabled withdrawal as a new request.

## Webhooks, recovery, and launch checks

Set up a signed HTTPS webhook in the Daya Dashboard. Verify the signature, deduplicate by event ID, and process asynchronously. Poll the resource and reconcile periodically if delivery is delayed. [Webhook verification](/stocks/webhooks/verification) explains the signing rules.

Before launch, check that you can:

* Authenticate with the minimum Stocks scopes.
* Complete KYC on the Stocks account associated with the API key, using its existing sign-in email.
* Receive a deposit into Stocks and assign it to the correct customer.
* Prevent an order when the market is closed or the amount is outside the asset limits.
* Handle an expired quote, failed order, duplicate webhook, and order request timeout.
* Reconcile all customer cash and position allocations with the Stocks account.
* Confirm trading and withdrawal availability with Daya before showing them as live.

For support, include the environment, endpoint, request ID, internal operation ID, Daya order or transaction ID, ticker, timestamp, and a redacted request. Never share an API key or full customer KYC data.