Quickstart

This guide walks through the full lifecycle of one order:

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.

1. Request Market Maker API access

Market Maker API access is permissioned. Request it from D1 first: see 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.

export D1_API_URL="<provided-by-d1>"
export D1_MM_API_KEY="<your-api-key>"

A trading key can move funds on your account. Keep it out of source control, logs, tickets and URLs. See Keeping your key safe.

3. Check status

curl "$D1_API_URL/mm/v1/status" \
  -H "Authorization: Bearer $D1_MM_API_KEY"

{
  "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.

4. List markets

curl "$D1_API_URL/mm/v1/markets?status=ACTIVE&limit=50" \
  -H "Authorization: Bearer $D1_MM_API_KEY"

{
  "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 explains every field.

5. Read the order book

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"

{
  "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.

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:

{
  "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

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.

curl "$D1_API_URL/mm/v1/executions?after=0&limit=100" \
  -H "Authorization: Bearer $D1_MM_API_KEY"

{
  "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.

9. Cancel remaining liquidity

Cancel one order:

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

{ "order": { "…": "…", "status": "CANCELLED", "cancelReason": "USER" }, "result": "CANCELLED", "serverTimeMs": "…" }

Or cancel every resting order on your account:

curl -X POST "$D1_API_URL/mm/v1/orders/cancel-all" \
  -H "Authorization: Bearer $D1_MM_API_KEY"

{ "cancelledOrderIds": ["<order-id>"], "cancelled": 1, "more": false, "serverTimeMs": "…" }

If more is true, call cancel-all again.

Next: Building a reliable client

Timeouts, retries, restarts and reconciliation for production bots.

Overview

Integration

API

Quickstart

1. Request Market Maker API access

2. Receive your API key and set up your environment

3. Check status

4. List markets

5. Read the order book

6. Place an order

7. Read the order

8. Reconcile executions

9. Cancel remaining liquidity

Next: Building a reliable client