Quickstart Guide

What is the Builder Service?

The Builder Service validates trading inputs and produces on-chain transactions for Ostium. By default it returns unsigned transactions that the trader signs and submits. If you send an X-API-Key and the delegate wallet is verified, the service can submit a delegated action on-chain for you.

Base URL

• Production: https://builder.ostiscan.xyz
• Local dev: http://localhost:3000

All endpoints are versioned under /v1.

Required Headers

• X-Trader-Address: trader wallet address (required)
• X-API-Key: optional, required for delegated mode

The header is case-insensitive. You can also pass the trader address via ?address=0x... on HTTP requests, but headers are preferred.

Quickstart (HTTP)

curl -X POST https://builder.ostiscan.xyz/v1/exchange/open \
  -H "Content-Type: application/json" \
  -H "X-Trader-Address: 0xYourWallet" \
  -d '{"open":{"a":0,"b":true,"p":"42500","s":"100","l":"10","t":"market"}}'

Example response (unsigned transaction):

{
  "transactions": [
    {
      "to": "0x...",
      "data": "0x...",
      "value": "0",
      "from": "0xYourWallet"
    }
  ]
}

Quickstart (WebSocket)

Connect to wss://<host>/v1/exchange/ws and send a JSON envelope:

{
  "id": "client-1",
  "action": "open",
  "headers": {
    "X-Trader-Address": "0xYourWallet",
    "X-API-Key": "optional"
  },
  "payload": {
    "open": {"a":0,"b":true,"p":"42500","s":"100","l":"10","t":"market"}
  }
}

API Documentation

Explore the API using our interactive OpenAPI documentation:

• Interactive API Docs - Try out endpoints directly in your browser

Next Steps

• Learn about authentication and delegated mode.
• Understand data types and formatting.
• Browse the HTTP API reference.
• Browse the WebSocket API reference.