> ## Documentation Index
> Fetch the complete documentation index at: https://docs.d1.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From API key to a placed, reconciled and cancelled order.

This guide walks through the full lifecycle of one order:

```text theme={null}
Request access → Receive API key → Configure D1_API_URL and D1_MM_API_KEY
→ GET /status → List markets → Read order book → Place, reconcile and cancel orders
```

The examples use `curl` and [`jq`](https://jqlang.org/).

## 1. Request Market Maker API access

Market Maker API access is permissioned. Request it from D1 first: see [Getting API access](https://docs.d1.exchange/market-makers/introduction.md#getting-api-access). To follow every step of this guide you need a trading key and trading enabled for your account. With a read key you can do steps 3 to 5, 7 and 8.

## 2. Receive your API key and set up your environment

D1 gives you two things during onboarding:

* the **API base URL**;
* an **API key**, shown to you once.

```bash theme={null}
export D1_API_URL="<provided-by-d1>"
export D1_MM_API_KEY="<your-api-key>"
```

> [!WARNING]
>
> A trading key can move funds on your account. Keep it out of source control, logs, tickets and URLs. See [Keeping your key safe](https://docs.d1.exchange/market-makers/authentication.md#keeping-your-key-safe).

## 3. Check status

```bash theme={null}
curl "$D1_API_URL/mm/v1/status" \
  -H "Authorization: Bearer $D1_MM_API_KEY"
```

```json theme={null}
{
  "apiVersion": "mm/v1",
  "dealer": { "id": "…", "status": "ACTIVE", "displayName": "Alpha Markets" },
  "credential": { "keyId": "…", "scopes": ["mm:read", "mm:trade"] },
  "capabilities": { "read": true, "trade": true, "writeOptions": false },
  "trading": { "available": true, "reason": null, "sellPolicy": "CLOSE_ONLY" },
  "limits": {
    "maxOpenExposure": { "units": "…", "decimals": 6 },
    "maxRestingOrders": 128,
    "maxRestingOrdersPerInstrument": 8
  }
}
```

A `200` means the key is valid and your account is active. Before you place orders, check that `trading.available` is `true`. If it is `false`, you can still read and cancel, but new orders are refused. See [Trading availability](https://docs.d1.exchange/market-makers/trading-rules.md#trading-availability).

## 4. List markets

```bash theme={null}
curl "$D1_API_URL/mm/v1/markets?status=ACTIVE&limit=50" \
  -H "Authorization: Bearer $D1_MM_API_KEY"
```

```json theme={null}
{
  "markets": [
    {
      "instrumentId": "<instrument-id>",
      "underlying": "BTC",
      "optionType": "CALL",
      "exerciseStyle": "EUROPEAN",
      "settlementType": "CASH",
      "strike": { "units": "100000", "decimals": 0 },
      "expirySeconds": "1800000000",
      "expiryMs": "1800000000000",
      "contractSize": { "units": "1", "decimals": 0 },
      "priceTick": { "units": "1", "decimals": 0 },
      "quantityStep": { "units": "1", "decimals": 0 },
      "quoteAsset": "USDC",
      "settlementAsset": "USDC",
      "collateralAsset": "USDC",
      "premiumUnit": "QUOTE_PER_CONTRACT",
      "status": "ACTIVE",
      "tradingPaused": false
    }
  ],
  "nextCursor": null,
  "limit": 50,
  "serverTimeMs": "1800000000456"
}
```

`priceTick` and `quantityStep` tell you which prices and quantities the market accepts. [Markets & Market Data](https://docs.d1.exchange/market-makers/market-data.md) explains every field.

## 5. Read the order book

```bash theme={null}
INSTRUMENT_ID=$(curl -s "$D1_API_URL/mm/v1/markets?status=ACTIVE" \
  -H "Authorization: Bearer $D1_MM_API_KEY" | jq -r '.markets[0].instrumentId')

curl "$D1_API_URL/mm/v1/markets/$INSTRUMENT_ID/orderbook?depth=10" \
  -H "Authorization: Bearer $D1_MM_API_KEY"
```

```json theme={null}
{
  "instrumentId": "<instrument-id>",
  "status": "ACTIVE",
  "tradingPaused": false,
  "depth": 10,
  "bids": [
    { "price": { "units": "100", "decimals": 0 }, "quantity": { "units": "12", "decimals": 0 }, "ownQuantity": { "units": "0", "decimals": 0 }, "partial": false }
  ],
  "asks": [
    { "price": { "units": "110", "decimals": 0 }, "quantity": { "units": "8", "decimals": 0 }, "ownQuantity": { "units": "0", "decimals": 0 }, "partial": false }
  ],
  "truncated": false,
  "serverTimeMs": "1800000000456"
}
```

## 6. Place an order

Every order needs a `clientOrderId` that you generate and **store before you send the request**. It is how you retry safely. See [Idempotency](https://docs.d1.exchange/market-makers/orders.md#clientorderid-and-idempotency).

```bash theme={null}
CLIENT_ORDER_ID="q-$(date +%Y%m%d)-000001"

curl -X POST "$D1_API_URL/mm/v1/orders" \
  -H "Authorization: Bearer $D1_MM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientOrderId": "'"$CLIENT_ORDER_ID"'",
    "instrumentId": "'"$INSTRUMENT_ID"'",
    "side": "BUY",
    "type": "LIMIT",
    "price": { "units": "105", "decimals": 0 },
    "quantity": { "units": "2", "decimals": 0 }
  }'
```

`201 Created` means D1 created the order:

```json theme={null}
{
  "order": {
    "orderId": "<order-id>",
    "clientOrderId": "q-20270115-000001",
    "instrumentId": "<instrument-id>",
    "side": "BUY",
    "type": "LIMIT",
    "price": { "units": "105", "decimals": 0 },
    "quantity": { "units": "2", "decimals": 0 },
    "requestedQuantity": { "units": "2", "decimals": 0 },
    "acceptedQuantity": { "units": "2", "decimals": 0 },
    "filledQuantity": { "units": "0", "decimals": 0 },
    "remainingQuantity": { "units": "2", "decimals": 0 },
    "cancelledQuantity": { "units": "0", "decimals": 0 },
    "reductionReason": null,
    "status": "OPEN",
    "cancelReason": null,
    "createdAtMs": "1800000000500",
    "updatedAtMs": "1800000000500",
    "filledAtMs": null,
    "cancelledAtMs": null
  },
  "duplicate": false,
  "serverTimeMs": "1800000000510"
}
```

If the request times out or you get a `5xx`, **send exactly the same request again with the same `clientOrderId`**. D1 returns the existing order with `200` and `duplicate: true` instead of creating a second one.

## 7. Read the order

```bash theme={null}
ORDER_ID="<order-id from the response>"

curl "$D1_API_URL/mm/v1/orders/$ORDER_ID" \
  -H "Authorization: Bearer $D1_MM_API_KEY"
```

The response is `{ order, serverTimeMs }`, with the same `order` fields as above. To see all orders still on the book, use `GET /mm/v1/orders?state=resting`.

## 8. Reconcile executions

Fills from your orders, whether they fill when placed or later while resting, appear on `/executions`. Start from `after=0` the first time, then from the checkpoint you saved.

```bash theme={null}
curl "$D1_API_URL/mm/v1/executions?after=0&limit=100" \
  -H "Authorization: Bearer $D1_MM_API_KEY"
```

```json theme={null}
{
  "executions": [
    {
      "executionSequence": "1",
      "fillId": "<fill-id>",
      "orderId": "<order-id>",
      "instrumentId": "<instrument-id>",
      "role": "MAKER",
      "side": "BUY",
      "price": { "units": "105", "decimals": 0 },
      "quantity": { "units": "1", "decimals": 0 },
      "premium": { "units": "105000000", "decimals": 6 },
      "executionIndex": "0",
      "createdAtMs": "1800000004000"
    }
  ],
  "nextAfter": "1",
  "hasMore": false,
  "limit": 100,
  "serverTimeMs": "1800000005000"
}
```

Process the page, save `nextAfter` durably, and use it as `after` next time. If `hasMore` is `true`, request again straight away. See [Fills & Executions](https://docs.d1.exchange/market-makers/executions.md).

## 9. Cancel remaining liquidity

Cancel one order:

```bash theme={null}
curl -X POST "$D1_API_URL/mm/v1/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $D1_MM_API_KEY"
```

```json theme={null}
{ "order": { "…": "…", "status": "CANCELLED", "cancelReason": "USER" }, "result": "CANCELLED", "serverTimeMs": "…" }
```

Or cancel every resting order on your account:

```bash theme={null}
curl -X POST "$D1_API_URL/mm/v1/orders/cancel-all" \
  -H "Authorization: Bearer $D1_MM_API_KEY"
```

```json theme={null}
{ "cancelledOrderIds": ["<order-id>"], "cancelled": 1, "more": false, "serverTimeMs": "…" }
```

If `more` is `true`, call `cancel-all` again.

> [card] [Next: Building a reliable client](https://docs.d1.exchange/market-makers/reliability.md)
>
> Timeouts, retries, restarts and reconciliation for production bots.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.