Building an agent

This walkthrough builds a minimal but complete futures agent. It signs in with its own wallet, reads the market, sizes an order with a preview, submits it, listens for fills on the real-time stream, and holds a kill switch.

All traffic goes through the OCX API gateway at https://api.ocx.global, written below as $API_BASE / API_BASE. Prices and quantities are JSON strings — keep them as strings end to end. Quantities are whole contracts. Market ids change as contracts expire; read them from /fut/markets.

The agent signs a SIWE message with a wallet key it controls and keeps the session token from the astra_session cookie. Authentication lists the required message fields and has a complete Node sign-in example (viem + siwe); wrap it in a signIn() function that returns the token.

JavaScript

const API_BASE = "https://api.ocx.global";

const token = await signIn();               // valid for 7 days — renew before expiry
const H = { Authorization: `Bearer ${token}` };

The wallet key and the session token both control the account. Use a dedicated wallet for the agent and load its key and token from a secret manager, never from source, prompts, or logs.

Step 2 — Read the market

Market data needs no auth. Discover markets, then read the book and stats for the one you want to trade.

# Dated futures: ids, contractSize, tickSize, expiry, mark
curl -s "$API_BASE/fut/markets"

# Order book snapshot
curl -s "$API_BASE/fut/orderbook/NDX-USDC-2026-12-18?depth=25"

# 24h stats (mark, change, volume, open interest)
curl -s "$API_BASE/fut/market-stats?marketId=NDX-USDC-2026-12-18"

# Fee schedule (query live rather than hardcoding)
curl -s "$API_BASE/fut/fees"

const markets = await fetch(`${API_BASE}/fut/markets`).then(r => r.json());
const market  = markets.find(m => m.baseSymbol === "NDX");
const book    = await fetch(`${API_BASE}/fut/orderbook/${market.id}?depth=25`).then(r => r.json());

// A trivial "signal": mid price from top of book
const bestBid = Number(book.bids[0]?.price);
const bestAsk = Number(book.asks[0]?.price);
const mid = (bestBid + bestAsk) / 2;

// Round to the market's tick before sending a price
const tick = Number(market.tickSize);
const limit = (Math.floor(mid / tick) * tick).toFixed(2);

For anything more than a one-shot decision, subscribe to GET /fut/book-stream instead of polling — it pushes the book each time it changes and is not rate-limited.

Step 3 — Size the order with a preview

Always dry-run before you commit. preview returns the notional, the estimated fee, and — critically — whether the order would pass the server-side margin check. It has no side effects.

curl -s -X POST "$API_BASE/fut/orders/preview" \
  -H "Authorization: Bearer $OCX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"marketId":"NDX-USDC-2026-12-18","side":"buy","type":"limit","price":"31000","quantity":"1"}'

const preview = await fetch(`${API_BASE}/fut/orders/preview`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json" },
  body: JSON.stringify({ marketId: market.id, side: "buy", type: "limit", price: limit, quantity: "1" }),
}).then(r => r.json());

if (!preview.approved) {
  // resize or fund — do not blindly retry
  throw new Error(`preview rejected: ${preview.reason}`);
}

boolean

Whether the order would pass the margin check. If false, read reason and resize or fund — do not retry the same order.

string

Margin the order needs.

string

Estimated fee for this order, with feePerLot and feeRole (maker for post-only orders, otherwise taker).

string

quantity × contractSize × price.

Step 4 — Submit the order

With an approved preview, place the order. Set a clientOrderId so a network retry can never create a duplicate.

curl -s -X POST "$API_BASE/fut/orders" \
  -H "Authorization: Bearer $OCX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "marketId":"NDX-USDC-2026-12-18","side":"buy","type":"limit",
    "price":"31000","quantity":"1","timeInForce":"gtc",
    "clientOrderId":"demo-agent-0001"
  }'

const { order, trades, position } = await fetch(`${API_BASE}/fut/orders`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json" },
  body: JSON.stringify({
    marketId: market.id, side: "buy", type: "limit",
    price: limit, quantity: "1", timeInForce: "gtc",
    clientOrderId: "demo-agent-0001",
  }),
}).then(r => r.json());

Order controls you’ll reach for:

Time in force

gtc rests until filled or cancelled; ioc fills what it can immediately then cancels the rest; fok fills fully or not at all.

postOnly / reduceOnly

postOnly rejects an order that would take liquidity (keeps you on the maker side). reduceOnly prevents an order from ever increasing your position — use it for exits.

Conditional orders

stopPrice, stopLossPrice, or takeProfitPrice make the order conditional: it is held and submitted once the OCX book mid reaches the trigger. See Place an order for the trigger directions.

Step 5 — Monitor fills over the stream

Open one connection to the futures account stream. On connect you receive a snapshot of your recent trades and positions across all futures markets; after that, delta events push new fills and position upserts as they happen. A fill shows up as a trade plus a position delta — that’s your signal to rebalance.

cURL

curl -N "$API_BASE/fut/stream/user" -H "Authorization: Bearer $OCX_TOKEN"

EventSource cannot send an Authorization header, so read the stream with fetch — the Fill stream guide has a complete reader with gap detection.

Streams can drop on network blips. Apply the initial snapshot, fold in each delta, check that eventSeq increases by exactly one, and reconnect (re-snapshotting) on disconnect or on a gap.

Between stream events, reconcile with the pull endpoints when you need certainty:

curl -s "$API_BASE/fut/positions"      -H "Authorization: Bearer $OCX_TOKEN"
curl -s "$API_BASE/fut/orders/open"    -H "Authorization: Bearer $OCX_TOKEN"
curl -s "$API_BASE/fut/trades"         -H "Authorization: Bearer $OCX_TOKEN"
curl -s "$API_BASE/portfolio/balances" -H "Authorization: Bearer $OCX_TOKEN"

Step 6 — Manage risk and shut down cleanly

Risk is enforced server-side, but your agent still owns its limits. Track NLV and margin headroom, de-risk proactively, and always have a kill path.

cURL

# Flatten a futures position (market close; omit quantity to close fully)
curl -s -X POST "$API_BASE/fut/positions/close" \
  -H "Authorization: Bearer $OCX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "marketId": "NDX-USDC-2026-12-18" }'

# Pull every futures order
curl -s -X POST "$API_BASE/fut/orders/cancel-all" \
  -H "Authorization: Bearer $OCX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

# Pull every option order
curl -s -X POST "$API_BASE/orders/cancel-all" \
  -H "Authorization: Bearer $OCX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "marketId": "" }'

JavaScript

async function killSwitch() {
  const opts = body => ({
    method: "POST",
    headers: { ...H, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  await Promise.all([
    fetch(`${API_BASE}/fut/orders/cancel-all`, opts({})),
    fetch(`${API_BASE}/orders/cancel-all`, opts({ marketId: "" })),
  ]);
}

// Wire killSwitch() to: feed loss, repeated errors, margin breach, or shutdown.

Handle INSUFFICIENT_MARGIN by resizing or funding, not by retrying. Back off on 429 and RATE_LIMITED. On 401, sign in again and re-snapshot.

The full loop

Provision

Create a dedicated wallet for the agent, fund it, and store its key in a secret manager.

Decide & size

Compute a signal, then preview to confirm margin, fee, and approval.

Execute

Place via /fut/orders, always with a clientOrderId.

React

Fold in fills and position deltas from the stream; adjust inventory.

Guard

Enforce your own limits; cancel-all or positions/close on breach, disconnect, or shutdown; renew the session before it expires.

Back to AI agents overview

Revisit the concepts: the agent loop, authentication, and server-side risk.

​Step 1 — Sign in and get a session token

​Step 2 — Read the market

​Step 3 — Size the order with a preview

​Step 4 — Submit the order

​Step 5 — Monitor fills over the stream

​Step 6 — Manage risk and shut down cleanly

​The full loop

Back to AI agents overview

Step 1 — Sign in and get a session token

Step 2 — Read the market

Step 3 — Size the order with a preview

Step 4 — Submit the order

Step 5 — Monitor fills over the stream

Step 6 — Manage risk and shut down cleanly

The full loop