Skip to content

Getting Started

!!! tip "OpenAPI spec available" The full machine-readable API spec lives at /openapi.json (also /openapi.yaml). Use it for codegen, Postman import, or to feed an AI agent the entire surface area in one fetch. See API Reference → Machine-readable OpenAPI spec.

Your identity is an EVM 0x address, passed lowercase on the wire. Every write is an EIP-712 typed struct signed under the PartiVault domain with your EVM key (see Authentication).

1. Register as a Builder

Register by signing the EIP-712 SessionBootstrap{user,timestamp} struct with your EVM wallet. This issues a session cookie and returns a stable builder_api_key:

curl -X POST https://oracle-api.parti.com/v1/builders/register \
  -H "Content-Type: application/json" \
  -d '{
    "user": "<your lowercase 0x address>",
    "name": "my-trading-app",
    "signature": "<65-byte EIP-712 SessionBootstrap signature>",
    "timestamp": 1777500000
  }'

Response:

{
  "api_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "wallet": "<your 0x address>",
  "name": "my-trading-app"
}

Save the api_key — it's your builder_api_key for fee attribution. The cookie lasts ~7 days; re-register after it expires (the same key comes back).

Or via admin (if you have an admin key):

curl -X POST https://oracle-api.parti.com/admin/builders \
  -H "X-Admin-Key: <admin key>" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "my-key", "name": "my-bot", "fee_bps": 50, "wallet": "<0x address>"}'

2. Fund Your Account

Get a deposit address (on the deposit host, not the gateway), then send USDG on Robinhood Chain to it:

curl https://oracle-deposit.parti.com/v1/deposit/robinhood-address/<your-lowercase-0x-address>

Send USDG on Robinhood Chain (mainnet 4663 for prod, testnet 46630 for staging) to the returned forwarder address. The watcher sweeps and credits your engine balance, usually under a minute. See Deposits.

3. Place Orders

All 4 order combinations work — Buy YES, Buy NO, Sell YES, Sell NO:

curl -X POST https://oracle-api.parti.com/v1/orders \
  -H "Content-Type: application/json" \
  --cookie "parti_oracle_session=<session cookie>" \
  -d '{
    "market_id": "abc123...",
    "user": "<your lowercase 0x address>",
    "side": "buy",
    "outcome": "yes",
    "price": 6500,
    "size": 100,
    "order_type": "gtc",
    "signature": "<65-byte EIP-712 Order signature — required>",
    "nonce": 1234567890123,
    "builder_api_key": "<your api key>"
  }'
  • price: 1-9999 basis points (6500 = 65 cents)
  • side: buy or sell
  • outcome: yes or no
  • order_type: gtc, ioc, fok, post_only
  • signature: 65-byte EIP-712 signature over the Order struct — required (never a placeholder; see Authentication)
  • nonce: per-user monotonic timestamp nonce (any strictly-increasing value)
  • builder_api_key: optional attribution. Your builder fee_bps (set in the builders table, not per-order) earns net-zero on each fill

No position needed to sell — the engine mints a YES+NO pair on match (Polymarket model).

4. Get All Your Orders

curl https://oracle-api.parti.com/v1/orders/all/<your-lowercase-0x-address> \
  --cookie "parti_oracle_session=<session cookie>"

Returns all open orders across all markets in a single call.

5. Cancel Orders

Cancels are authorized by the session cookie alone — no signature, no CancelAll struct:

# Cancel all orders
curl -X POST https://oracle-api.parti.com/v1/orders/cancel-all \
  -H "Content-Type: application/json" \
  --cookie "parti_oracle_session=<session cookie>" \
  -d '{
    "user": "<your lowercase 0x address>",
    "builder_api_key": "<your api key>"
  }'

6. View Your Revenue

# Get your trade history
curl https://oracle-api.parti.com/v1/trades/<your-lowercase-0x-address>?limit=100

Base URLs

Environment Gateway (REST) WebSocket
Production https://oracle-api.parti.com wss://oracle-api.parti.com/v1/ws
Staging https://oracle-gateway.pbcapps.dev wss://oracle-gateway.pbcapps.dev/v1/ws

Rate Limits

  • 600 orders/min per wallet
  • 10 requests/sec per IP on public endpoints
  • Internal services bypass via X-Internal-Key

Sandbox network access

Some AI coding sandboxes (web-based IDEs, agent runtimes) ship with a deny-by-default egress allowlist. If a curl or fetch against the gateway returns an x-deny-reason: host_not_allowed header, the request never left the sandbox — it has nothing to do with our CORS config.

To unblock, add these hosts to your sandbox's outbound allowlist:

  • oracle-api.parti.com (prod gateway + WebSocket)
  • oracle-gateway.pbcapps.dev (staging gateway + WebSocket)
  • oracle-deposit.parti.com (prod deposit host)

Fetching the OpenAPI spec is the simplest connectivity probe:

curl -sSf https://oracle-gateway.pbcapps.dev/openapi.json | head -c 200

A non-empty JSON response confirms the host is reachable end-to-end.