Ostium Builder Service - Compact API Spec

This page is optimized for AI agents and LLM tooling that need compact API context.

Quick Reference

Param keys: a=asset index, b=buy/long, p=price, s=size/collateral, l=leverage, t=type/trade index, i=index, o=order ID, r=close %, tp=take profit, sl=stop loss, sp=slippage %, bd=builder config

Base

• Base URL: https://builder.ostiscan.xyz
• Version: /v1
• Local: http://localhost:3000

Headers

• X-Trader-Address: trader wallet (required)
• X-API-Key: optional; required for delegated mode
• Content-Type: application/json (or text/plain with JSON body)

Auth / Delegated Mode

• If X-API-Key is present, the delegate wallet must be verified.
• Delegated mode supports one action per request.
• Delegated response: { txHash, smartAccountAddress }.

Error Envelope (HTTP)

{ "error": "message", "code": 400, "errorCode": "INVALID_REQUEST", "details": {"validationErrors": {"field": ["msg"]}} }

HTTP Endpoints

Health

• GET /v1/health
• GET /v1/exchange/health

Balance

• GET /v1/balance/usdc (requires X-Trader-Address)

Exchange (unsigned txs by default)

• POST /v1/exchange/open

  {
    open: {        // Single open object
      a: 0,        // Asset index (pair ID)
      b: true,     // Buy=long (true) or sell=short (false)
      p: "42500",  // Price (string, >0)
      s: "100",    // Size/collateral in USD (string, min $5)
      l: "10",     // Leverage (string, >=1)
      t: "market", // Type: "market", "limit", "stop"
      tp?: "43000", // Take profit price (optional)
      sl?: "41000"  // Stop loss price (optional)
    },
    sp?: 0.25,     // Slippage % (0-100, default 0.25)
    bd?: {         // Builder fee config (optional)
      b: "0x...",  // Builder address
      f: 0.1       // Fee % (0-0.5)
    }
  }

• POST /v1/exchange/close

  {
    closes: [{
      a: 0,        // Asset index
      t: 0,        // Trade index
      p: "42500",  // Current price (string)
      r: 100       // Close % (1-100)
    }],
    sp?: 0.25      // Slippage %
  }

• POST /v1/exchange/cancel

  {
    cancels: [{
      t: "limit",  // Type: "limit", "close", "open"
      // For limit orders:
      a?: 0,       // Asset index (required for limit)
      i?: 0,       // Order index (required for limit)
      // For timeout cancels:
      o?: 123      // Order ID (required for close/open)
    }]
  }

• POST /v1/exchange/modify

  {
    a: 0,          // Asset index
    i: 0,          // Position/order index
    p?: "42500",   // New price (for limit orders)
    tp?: "43000",  // New take profit
    sl?: "41000"   // New stop loss
  }

• POST /v1/exchange/margin

  {
    a: 0,          // Asset index
    i: 0,          // Position index
    amount: "50"   // Amount (string, +add/-remove)
  }

Auth (Delegate Wallets)

• POST /v1/auth/create
  • Returns: { apiKey, smartAccountAddress, delegateApprovalTx, usdcApprovalRequired, usdcApprovalTx?, chainId }
• POST /v1/auth/verify-auth (requires X-API-Key)
  • Returns: { verified, smartAccountAddress, allowance }
• POST /v1/auth/cancel
  • Returns: { message, nonce, expiresAt, smartAccountAddress }
• POST /v1/auth/verify-cancel
  • Body: { message, signature }
• POST /v1/auth/revoke
  • Returns: { removeDelegateTx, smartAccountAddress, message, nonce, expiresAt }
• POST /v1/auth/verify-revoke
  • Body: { message, signature }

WebSocket

Trade Actions

• Endpoint: wss://builder.ostiscan.xyz/v1/exchange/ws

Request:

{
  "id": "client-123",     // Client-side request ID
  "action": "open",       // Actions: open/close/cancel/modify/margin/health
  "headers": {
    "X-Trader-Address": "0x...",
    "X-API-Key": "..."    // Optional, for delegated mode
  },
  "payload": {            // Same as HTTP body for each action
    "open": { ... }       // Single open object
  }
}

Success response:

{
  "id": "client-123",
  "ok": true,
  "data": {
    "transactions": [...] // Unsigned txs (non-delegated)
    // OR
    "txHash": "0x...",    // Delegated mode response
    "smartAccountAddress": "0x..."
  }
}

Error response:

{
  "id": "client-123",
  "ok": false,
  "error": {
    "message": "...",
    "code": 400,
    "errorCode": "INVALID_REQUEST"
  }
}

• Keepalive: {"action": "health"} (no headers/payload needed)
• Rate limit: 100 msg/min per connection

Market Stream

• Endpoint: wss://builder.ostiscan.xyz/v1/market/stream

Emits raw ticks:

{ "feed_id":"BTC-USD", "bid":..., "mid":..., "ask":..., "from":"USD", "to":"BTC", "timestampSeconds": ... }