Quickstart

You can get your first successful response from the Drazill API before you sign up for anything: public market data needs no authentication. From there it is three short steps to an authenticated call, a paper (test-money) order, and a realtime price tick.

Every request lives under the /api/v1 prefix.

Step 1 — Read a market (no auth)

Listing markets is a public read. This works for every reader, right now:

$
curl "https://staging.drazill.com/api/v1/markets?limit=3"

The response is a page envelope. Each market carries its outcomes, and each outcome’s price is a decimal string in [0, 1] — the market’s implied probability for that outcome. (Prices across a market’s outcomes always sum to exactly 1 — see How pricing works.)

1
{
2
  "items": [
3
    {
4
      "id": "mkt_example_toronto_rain",
5
      "slug": "will-it-rain-in-toronto",
6
      "title": "Will it rain in Toronto tomorrow?",
7
      "total_volume": "12840.00",
8
      "outcomes": [
9
        { "id": "out_example_yes", "name": "Yes", "price": "0.63" },
10
        { "id": "out_example_no",  "name": "No",  "price": "0.37" }
11
      ]
12
    }
13
  ],
14
  "total": 1
15
}

Environments

Point the SDKs at an environment with DRAZILL_BASE_URL (and DRAZILL_WS_URL for realtime); both default to staging in the examples so you can run them safely as-is.

Step 2 — Get an API key

Create a key in the staging developer dashboard. Prefer a test key first: test keys carry the drzl_test_ prefix, trade paper money only, and are the only keys you should ever place in a browser or a shared notebook. Live keys carry drzl_live_. The full key is shown once at creation — store it securely.

Test keys require the sandbox (DEVELOPER_SANDBOX_ENABLED), which is on by default on staging and off on production — see Sandbox for the per-environment table.

Step 3 — Make an authenticated call

Send the key in the X-API-Key header. GET /auth/me echoes the authenticated identity — a one-line proof your key works:

$
curl -H "X-API-Key: $DRAZILL_API_KEY" \
>
  https://staging.drazill.com/api/v1/auth/me

Keep the key server-side. See Authentication for scopes, key classes, and why browser apps must proxy through your own backend.

Step 4 — Place a paper order

With a drzl_test_ key, the ordinary trading endpoints route onto the price-isolated paper engine — the same request you would send in production, with zero real-money risk. Preview a fee-inclusive quote, then place the order binding that quote and an idempotency key so a client-side retry can never double-place:

1
idempotency_key = f"quickstart-trade-{uuid.uuid4()}"
2
result = client.orders.place_order(
3
    models.OrderCreate(
4
        market_id=market.id,
5
        outcome_id=outcome_id,
6
        side="BUY",
7
        type="MARKET",
8
        quantity=ORDER_QTY,
9
        preview_quote_token=quote.quote_token,
10
    ),
11
    include_receipt=True,
12
    request_options=RequestOptions(idempotency_key=idempotency_key),
13
)

A drzl_test_ key is hard-rejected with TEST_KEY_LIVE_ENDPOINT if it ever hits a real-money endpoint, so a paper key cannot move real funds. See Paper vs live.

Step 5 — Follow a live price tick

Open a WebSocket to /ws, authenticate with your key, and subscribe to prices:{outcome_id} for price-tick updates (the lightest realtime channel — one price_tick per price move):

1
import asyncio
2
from drazill import DrazillClient
3
4
client = DrazillClient(api_key="<DRAZILL_API_KEY>")
5
ws = client.ws()
6
7
async def stream():
8
    await ws.connect()
9
    await ws.subscribe("orderbook:OUTCOME_UUID")
10
    await ws.subscribe("trades:MARKET_UUID")
11
12
    async for event in ws.listen():
13
        event_type = event.get("type")
14
        channel = event.get("channel", "")
15
        data = event.get("data", {})
16
        if event_type == "orderbook_update":
17
            print(f"Order book update on {channel}: {data}")
18
        elif event_type == "trade":
19
            print(f"Trade on {channel}: price={data.get('price')}")
20
21
asyncio.run(stream())

The full realtime contract — every channel, the sequence/replay guarantees, and the raw message protocol — lives under Realtime.

Where next

• Authentication — scopes, key classes, and request signing.
• Concepts — how the hybrid order-book + LMSR engine actually prices.
• Sandbox — the paper-trading environment end to end.
• SDKs — install the Python and TypeScript clients.