> For the complete documentation index, see [llms.txt](https://docs.ichigeki.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ichigeki.app/developers/derive-integration.md).

# Derive integration

Everything ICHIGEKI reads at launch comes from Derive's **public** API — no API key, no private endpoints, no server-side secrets. This page documents exactly what is used and how.

## Environments

| Env     | Base URL                        |
| ------- | ------------------------------- |
| mainnet | `https://api.lyra.finance`      |
| testnet | `https://api-demo.lyra.finance` |

Selected by `NEXT_PUBLIC_DERIVE_ENV` (`mainnet` default, `testnet` for the api-demo environment). WebSocket URL is the same host with `wss` and `/ws`. All public endpoints are `POST` with a JSON body, returning `{ result }` on success or `{ error }` on failure — `src/lib/derive/client.ts` wraps this and throws `DeriveApiError` on either transport or API-level errors.

## Endpoints used

### `public/get_instruments`

```json
{ "currency": "BTC", "instrument_type": "option", "expired": false }
```

Returns all active BTC option listings. ICHIGEKI filters to `is_active` with `option_details`, derives the set of expiries, and picks the nearest future one. Instrument metadata carries `taker_fee_rate` and `base_fee` per instrument — fees are computed from these live values, never hardcoded.

### `public/get_ticker`

```json
{ "instrument_name": "BTC-20260829-115000-C" }
```

Returns best bid/ask with sizes, mark price, index price, IV and Greeks for one instrument. The ladder is built from these.

## Instrument naming

```
BTC-YYYYMMDD-STRIKE-C|P

BTC-20260829-115000-C   → BTC call, strike 115,000, expiring 2026-08-29 (08:00 UTC)
BTC-20260829-110000-P   → BTC put,  strike 110,000, same expiry
```

The date is the expiry's UTC calendar date; dailies settle at 08:00 UTC. `option_details.expiry` carries the exact unix timestamp — use it, not the name, for countdown math.

## Rate-limit posture

Derive's public rate limits are sized for individual trading interfaces. ICHIGEKI stays comfortably inside them by bounding what it polls:

* **Instruments:** one `get_instruments` call per minute per currency (TanStack Query, `staleTime` = `refetchInterval` = 60s).
* **Tickers:** every 5 seconds, but only for a bounded near-the-money window (roughly `2 × maxRows`, min 12 instruments) around the median listed strike — never all 44 strikes on the chain.
* All requests carry abort signals so unmounted views stop polling immediately.

The honest-MVP cadence is REST polling; the upgrade path is the public WebSocket (orderbook and ticker channels), which replaces the 5s ticker loop without touching the ladder logic. A multi-user production deployment will need Derive-approved limits — see [Roadmap](/project/roadmap.md).

## Trading (Phase 2)

Order submission is behind a hard gate in `src/lib/derive/orders.ts`:

* `isTradingEnabled()` — false until the trading phase ships; UI renders read-only.
* `submitOrder(params)` — resolves to an order acknowledgment, or throws `TradingNotEnabledError` while the gate is closed.

The Phase 2 plan, mirroring Derive's documented auth model:

1. Wallet login via signature (`public/login` flow) to associate the user's wallet with their subaccount.
2. **Session-key registration**: the user signs a transaction authorizing a scoped, expiring session key — order signing only, no withdrawal scope, revocable in the interface.
3. Signed order submission (market and limit) through the private API, with the optional `client` label / builder-fee fields applied only after written confirmation from Derive.
4. Private subscriptions for open orders, fills, positions and settlement history.

## What the API does not provide

Worth restating for contributors, because it bounds the product:

* No way to create new expiries or strikes and inherit liquidity
* No way to require market makers to quote anything
* No depth or execution guarantees
* No transfer of positions to other chains
* No guaranteed access to the operated matching engine

See [Risks](/security/risks.md) for the operational implications.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ichigeki.app/developers/derive-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.