> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocx.global/llms.txt
> Use this file to discover all available pages before exploring further.

# AI agents on OCX

> Build autonomous trading agents on the same public API a human trader uses — read market data, decide, place and cancel orders, and manage risk, all under a programmatic API key.

An AI agent trades on OCX exactly the way a human client does: it reads market
data, forms a view, places and cancels orders, watches its fills, and manages
risk. There is no separate "agent API" — your agent speaks the same public REST
and streaming surface, and authenticates headlessly with an **API key** instead
of a browser session.

<Info>
  Everything an agent needs is public and documented. Market data is open, the
  order lifecycle is a handful of JSON endpoints, and execution updates arrive on
  a single Server-Sent Events stream. If you can write an HTTP client, you can
  write an OCX agent.
</Info>

## The agent loop

Every OCX agent, from a simple signal follower to a full market-making bot,
reduces to the same cycle. Keep it tight and idempotent.

<Steps>
  <Step title="Read">
    Pull instruments, order books, stats, and candles — or subscribe to the live
    stream — to build your current view of the market.
  </Step>

  <Step title="Decide">
    Turn that view into an intent: an order to place, a quote ladder to refresh,
    or a position to reduce.
  </Step>

  <Step title="Act">
    Preview to size safely, then place or cancel. Use a `clientOrderId` so retries
    never double-submit.
  </Step>

  <Step title="Monitor">
    Consume the real-time stream to detect fills and position changes the instant
    they happen.
  </Step>

  <Step title="Manage risk">
    Track margin headroom, de-risk proactively, and wire `cancel-all` to your
    kill switch.
  </Step>
</Steps>

## What your agent talks to

<CardGroup cols={2}>
  <Card title="Market data (public)" icon="chart-line">
    Instruments, order books, 24h stats, fee tiers, and candles. No credentials
    required — sending your key is harmless but optional.
  </Card>

  <Card title="Trading (API key)" icon="bolt">
    Preview, place, and cancel orders; refresh multi-level quote ladders in one
    atomic call; flatten positions.
  </Card>

  <Card title="Real-time stream (SSE)" icon="satellite-dish">
    One connection per market delivers the order book, your fills, and your
    position updates as they occur.
  </Card>

  <Card title="Account reads" icon="wallet">
    Positions, open orders, trades, and balances — for reconciliation and risk
    checks between stream events.
  </Card>
</CardGroup>

## Programmatic authentication

A human owner signs in once with Sign-In With Ethereum (SIWE), then provisions a
scoped, IP-pinned, expiring **API key** for the agent. The agent sends that key
as an `x-api-key` header on every request and never touches a wallet again.

```bash theme={null}
POST {API_BASE}/perps/me/api-keys
Content-Type: application/json

{ "name": "signal-agent", "scope": "trade", "allowedIps": ["203.0.113.7"], "expiresInDays": 90 }
→ { "id": "01H…", "secret": "ocx_sk_…", "message": "Copy this secret now — it will not be shown again." }
```

<Warning>
  The `secret` is returned **once** and never again. Store it in a secret manager,
  never in source or logs. If it leaks, revoke the key immediately with
  `DELETE {API_BASE}/perps/me/api-keys/{id}`.
</Warning>

### Scopes — grant least privilege

<CardGroup cols={2}>
  <Card title="read" icon="eye">
    Market data plus your own account reads. Give this to research, monitoring,
    or signal-only agents that never trade.
  </Card>

  <Card title="trade" icon="key">
    Everything `read` can do, plus order and quote actions. Reserve this for
    agents that actually execute.
  </Card>
</CardGroup>

Keys record their last-used time and IP for audit, and a key can never create or
revoke another key — key management stays session-only.

<Note>
  Today the gateway accepts API keys on the high-throughput programmatic paths:
  order **preview**, **bulk quotes**, and **cancel-all**. The single-order
  place/cancel-by-id endpoints and the real-time stream run under a signed-in
  session. Agents that need discrete headless order placement should use the
  bulk-quote path or run under a session token. This coverage is expanding —
  check the current gateway policy for your integration.
</Note>

## Pricing your agent should understand

Your agent consumes prices and marks; it does not recompute the exchange's
internals. Treat the following as inputs to your strategy.

<AccordionGroup>
  <Accordion title="Perpetual mark and funding">
    Perpetuals track an underlying index. Funding is exchanged periodically based
    on the gap between the perp's mark and its index (plus a carry term), which
    nudges the perp price toward the underlying. Read the current funding context
    from `/perps/market-stats`, and fund your account to hold positions through
    funding periods.
  </Accordion>

  <Accordion title="Dated futures fair value">
    A dated future is priced off spot plus a cost-of-carry term to expiry, so it
    trades at a premium or discount to spot (contango or backwardation). See the
    [Futures methodology](/methodology/futures) for the concept.
  </Accordion>

  <Accordion title="Option marks">
    Option `mark`, `iv`, and `delta` on the board are OCX reference marks computed
    from a fitted volatility surface — published for reference and risk. The
    tradable prices are always the order book. See the
    [Options methodology](/methodology/options).
  </Accordion>
</AccordionGroup>

## Risk is enforced server-side

OCX runs portfolio margin on the exchange side: every order passes a margin gate
before acceptance. A rejected order returns an insufficient-margin error —
**handle it, don't retry blindly.** Positions that breach maintenance margin are
liquidated by the exchange, with an insurance fund backstopping bad debt. Your
agent should track its own margin headroom from `balances` and `positions` and
de-risk before it gets there.

<Tip>
  Build three safety reflexes into every agent from day one: use `reduceOnly` for
  exit-only orders, wire `cancel-all` to a single kill switch, and back off on
  `429` rate-limit responses. Respect the `X-RateLimit-*` headers.
</Tip>

## Next step

<Card title="Build an agent" icon="robot" href="/ai-agents/building-an-agent">
  A concrete walkthrough: authenticate, pull market data, size an order, submit
  it, monitor fills on the stream, and manage risk — with code.
</Card>