MCP tool reference
Every tool the Sphinx MCP server (0.1.0) exposes, generated from the running server so it cannot drift. Read the overview for setup and the order flow for how the write tools fit together.
Conventions: money is integer µUSDC (1e-6 USDC); prices are integer pips — event contracts 1–9999 (= $0.0001–$0.9999), margined instruments signed ticks × tick_size_uusdc from get_contract_spec; sizes are whole contracts. Every result is returned both as JSON text and as structuredContent. A failed call returns isError: true with { error, code, status, details, correlation_id, hint } — pass code to explain_reject_code.
Summary
| Tool | Tier | Hints | Wraps |
|---|---|---|---|
list_markets | Read (keyless) | read-only, idempotent | list-instruments, list-margin-metadata, list-contract-specs, get-fees, list-instruments-full |
get_market | Read (keyless) | read-only, idempotent | list-instruments, list-margin-metadata, get-contract-spec, get-orderbook |
get_orderbook | Read (keyless) | read-only, idempotent | get-orderbook |
get_candles | Read (keyless) | read-only, idempotent | get-candles |
get_trades | Read (keyless) | read-only, idempotent | get-instrument-trades |
get_funding | Read (keyless) | read-only, idempotent | get-instrument-funding |
get_open_interest | Read (keyless) | read-only, idempotent | get-open-interest |
get_contract_spec | Read (keyless) | read-only, idempotent | get-contract-spec |
get_fees | Read (keyless) | read-only, idempotent | get-fees |
get_ercot_prices | Read (keyless) | read-only, idempotent | get-ercot-prices |
get_venue_status | Read (keyless) | read-only, idempotent | get-venue-health, get-service-status |
explain_reject_code | Read (keyless) | read-only, idempotent | — |
get_account | Read (credential) | read-only, idempotent | get-account-snapshot |
get_positions | Read (credential) | read-only, idempotent | get-positions |
get_open_orders | Read (credential) | read-only, idempotent | list-open-orders |
get_fills | Read (credential) | read-only, idempotent | list-fills |
get_margin | Read (credential) | read-only, idempotent | get-margin-info |
get_limits | Read (credential) | read-only, idempotent | get-account-limits |
get_pending_orders | Read (credential) | read-only, idempotent | list-pending-orders |
get_funding_payments | Read (credential) | read-only, idempotent | list-funding-payments |
get_funding_summary | Read (credential) | read-only, idempotent | get-funding-summary |
get_deadman | Read (credential) | read-only, idempotent | get-deadman |
stage_order | Write (credential) | read-only, idempotent | stage-order |
place_order | Write (credential) | — | place-order |
cancel_order | Write (credential) | destructive, idempotent | cancel-order |
cancel_all_orders | Write (credential) | destructive, idempotent | cancel-all |
set_deadman | Write (credential) | destructive, idempotent | set-deadman |
Read (keyless)
No credential needed. These call public venue routes only; a credential you supply is never sent on them.
list_markets
List markets · read-only, idempotent
Every listed instrument with symbol, product class (perp | future | event), state, unit, contract size and maker/taker fee bps. Tick size, margin bps and price bands are per instrument: get_market or get_contract_spec. Prices on the venue are integer pips (event contracts: 1–9999 = $0.0001–$0.9999; margined: signed ticks × tick_size_uusdc). Default returns trading instruments only.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
state | trading / all | no | "trading" | trading = only instruments currently accepting orders |
class | perp / future / event / all | no | "all" |
Returns. markets[] — one row per instrument: instrument_id, symbol, display_name, class (perp / future / event), state, unit, contract_size, expiry_date (futures), price_feed_id, manifest_hash, maker_fee_rate_bps, taker_fee_rate_bps; event contracts add criterion and closes_at_ns.
Wraps. list-instruments, list-margin-metadata, list-contract-specs, get-fees, list-instruments-full
get_market
Get market · read-only, idempotent
One instrument in full: listing state, metadata, contract spec (tick size, bands, margin, fees, price domain) and the top of book. Event contracts (YES/NO) carry their resolution criterion.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | yes | — |
Returns. market (a list_markets row), contract_spec (tick size, IM/MM bps, price bands, fee model, signed price domain, funding caps), manifest_hash, and top_of_book (best_yes_bid, best_yes_ask — for event books the ask is derived from the best NO bid at 10000 − price).
Wraps. list-instruments, list-margin-metadata, get-contract-spec, get-orderbook
get_orderbook
Get orderbook · read-only, idempotent
Resting liquidity, best price first, trimmed to depth levels per side. Margined books return yes_bids (buys) and yes_asks (sells) in signed ticks. Event books are YES-collapsed: yes_bids are YES buys and no_bids are NO buys, i.e. a YES sell at p rests as a NO bid at 10000−p.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | yes | — | |
depth | integer (min 1, max 50) | no | 10 |
Returns. yes_bids and no_bids (event books, YES-collapsed) or yes_bids and yes_asks (margined books, signed ticks), each { price_pips, count } best first, at most depth levels per side.
Wraps. get-orderbook
get_candles
Get candles · read-only, idempotent
OHLCV bars (prices in pips, volume in contracts, t = bar start Unix seconds, oldest first). Use countback for the latest N bars, or from/to (Unix seconds) for a range; history older than memory is served from the durable store.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | yes | — | |
resolution | 1m / 5m / 15m / 1h / 1d | no | "1h" | |
countback | integer (min 1, max 2000) | no | — | latest N bars (default 120 when from/to are absent) |
from | integer | no | — | Unix seconds, inclusive bar start |
to | integer | no | — | Unix seconds |
side | yes / no | no | — | event contracts only; default yes |
Returns. bars[] of { t, o, h, l, c, v, closed } oldest first — t bar start in Unix seconds, prices in pips, v in contracts; the last bar is in flight unless closed is true.
Wraps. get-candles
get_trades
Get trades · read-only, idempotent
Recent public prints for an instrument, newest first, with a cursor for older pages.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | yes | — | |
limit | integer (min 1, max 500) | no | 50 | |
cursor | string | no | — |
Returns. trades[] newest first (event_seq, ts_ns, price_pips, count, taker_side) and next_cursor for older pages.
Wraps. get-instrument-trades
get_funding
Get funding history · read-only, idempotent
Funding boundaries for a perpetual: rate_fp8 (per interval, fixed-point 1e-8, positive = longs pay), premium and interest components, skipped flags. Newest first with a cursor.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | yes | — | |
limit | integer (min 1, max 500) | no | 48 | |
cursor | string | no | — |
Returns. funding[] newest first (boundary_ns, rate_fp8, premium_fp8, interest_fp8, skipped) and next_cursor.
Wraps. get-instrument-funding
get_open_interest
Get open interest · read-only, idempotent
One-sided open interest per instrument in contracts and mark-notional µUSDC.
No parameters.
Returns. rows[] of { instrument_id, open_interest_contracts, open_interest_uusdc } at engine_seq_applied.
Wraps. get-open-interest
get_contract_spec
Get contract spec · read-only, idempotent
The engine's contract specification for an instrument: tick_size_uusdc, initial/maintenance margin bps, price bands, fee model and rates, signed price domain, funding caps, contract_size and unit.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | yes | — |
Returns. spec — the engine's contract specification — plus manifest_hash and engine_seq_applied.
Wraps. get-contract-spec
get_fees
Get fee schedule · read-only, idempotent
Venue fee schedule per instrument: maker/taker rate bps (signed; negative maker = rebate), flat per-contract fees, delivery fees. Crossing the spread usually costs more than the fee — compare with stage_order's est_total_cost.
No parameters.
Returns. fees[] per instrument: maker_fee_rate_bps (signed; negative = rebate), taker_fee_rate_bps, flat per-contract fees, funding and delivery fee flags.
Wraps. get-fees
get_ercot_prices
Get ERCOT prices · read-only, idempotent
Latest ERCOT real-time prices per settlement point: 5-minute LMP and 15-minute SPP (the RT perps' settlement basis) in µUSDC per MWh with ERCOT's own timestamps and staleness flags, plus the listed perpetual on each point. Optionally filter by point name (e.g. HB_NORTH, LZ_WEST).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
point | string | no | — | settlement point name; omit for all |
Returns. points[] — per settlement point: lmp (5-minute) and spp (15-minute) as { value_uusdc, observed_at_ns, stale } or null, plus the listed perpetual's instrument_id and symbol; as_of_ns is the server time the staleness flags were evaluated.
Wraps. get-ercot-prices
get_venue_status
Get venue status · read-only, idempotent
Venue health (books two-sided, tape freshness, disk) and per-service status. Read this first when orders reject unexpectedly.
No parameters.
Returns. venue (status, books_two_sided, last_fill_age_s, disk_used_pct, failing reasons when unhealthy) and services (per-service status, latency_ms).
Wraps. get-venue-health, get-service-status
explain_reject_code
Explain a reject or error code · read-only, idempotent
What an order reject_reason, cancel reject, or Edge error code means and what to do next.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
code | string | yes | — |
Returns. code, kind (order_reject / cancel_reject / edge_error), meaning, action.
Read (credential)
Require a Sphinx API credential. Without one the tool returns credential_required and the venue is not contacted.
get_account
Get account snapshot · read-only, idempotent
Balances (atomic µUSDC: total = available + held), positions, open orders, pending withdrawals and — for the margin sub-account — equity, IM held, maintenance requirement and free collateral. Requires a credential.
No parameters.
Returns. The account snapshot: balances[] (atomic µUSDC — total, held, available), positions[], open_orders[], pending_withdrawals[], and margin (equity, im_held, mm_required, free_collateral, margin_withdrawable, per-position margin) for the margin sub-account.
Wraps. get-account-snapshot
get_positions
Get positions · read-only, idempotent
Open positions per instrument and sub-account (signed_qty for margined; yes/no positions for event contracts). Requires a credential.
No parameters.
Returns. positions[] — instrument_id, sub_account_id, signed_qty (margined) or yes_position / no_position (event contracts).
Wraps. get-positions
get_open_orders
Get open orders · read-only, idempotent
Your resting orders (order_id, instrument, side/action, price_pips, remaining quantity). Optionally filter by instrument. Requires a credential.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | no | — |
Returns. orders[] — order_id, instrument_id, sub_account_id, api_side, action, order_type, tif, price_pips, remaining quantity.
Wraps. list-open-orders
get_fills
Get fills · read-only, idempotent
Your fills, newest first, with your side (maker/taker), action, price, count, signed fee_uusdc and tag (normal | liquidation | adl). Cursor for older pages. Requires a credential.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer (min 1, max 500) | no | 50 | |
cursor | string | no | — |
Returns. fills[] newest first — your_side (maker/taker), your_action, price_pips, count, signed fee_uusdc, tag (normal / liquidation / adl) — and next_cursor.
Wraps. list-fills
get_margin
Get margin info · read-only, idempotent
The margin sub-account's equity, initial margin held, maintenance requirement, free and withdrawable collateral, reserved funding and per-position margin. Requires a credential.
No parameters.
Returns. The margin sub-account block: equity, im_held, mm_required, free_collateral, margin_withdrawable, reserved_funding, positions[].
Wraps. get-margin-info
get_limits
Get limits and scope · read-only, idempotent
This credential's write rate-limit window (enabled, limit, window_s, remaining, reset_at_ns), its scope (instrument_allowlist, max_order_notional_uusdc, max_daily_notional_uusdc, max_open_orders, approval_mode), today's usage against the daily cap (daily: notional_used_uusdc, orders, notional_cap_uusdc) and the agent descriptor. Read this before trading to know your own caps. Requires a credential.
No parameters.
Returns. credential_id, write (enabled, limit, window_s, remaining, reset_at_ns), scope (instrument_allowlist, max_order_notional_uusdc, max_daily_notional_uusdc, max_open_orders, approval_mode), daily (day_utc, notional_used_uusdc, orders, notional_cap_uusdc) and agent.
Wraps. get-account-limits
get_pending_orders
Get orders awaiting human approval · read-only, idempotent
Orders this account's require_human credentials have parked (place_order returned pending_approval) that are still undecided and unexpired: pending_id, the order fields, notional_uusdc, credential_id, agent, expires_at_ns. A human approves or rejects them in the terminal; this tool only reads. Requires a credential.
No parameters.
Returns. pending[] — parked orders: pending_id, state, the order fields, notional_uusdc, credential_id, agent, created_at_ns, expires_at_ns.
Wraps. list-pending-orders
get_funding_payments
Get funding payments · read-only, idempotent
Your funding legs as the engine booked them, newest first: per boundary and perpetual, the signed payment_uusdc (negative = you paid, positive = you received), the snapshot position_qty, the boundary mark_ticks, the notional_uusdc it was computed on, the settled rate_fp8 and whether the dollar cap clipped it. totals sums the page. Optional instrument_id filter, cursor for older pages. History begins at the venue's first boundary after API 0.15.0. Requires a credential.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | no | — | |
since_boundary_ns | integer (min 0) | no | — | |
limit | integer (min 1, max 1000) | no | 50 | |
cursor | string | no | — |
Returns. payments[] newest first (event_seq, boundary_ns, instrument_id, rate_fp8, position_qty, mark_ticks, notional_uusdc, signed payment_uusdc, dollar_capped), next_cursor, and totals (paid_uusdc, received_uusdc, net_uusdc, boundaries) for the page.
Wraps. list-funding-payments
get_funding_summary
Get funding summary · read-only, idempotent
Per perpetual you hold or were paid on: net funding over 24 h / 7 d / all recorded history, the latest payment, your current position and mark, the last settled rate, and predicted_next_uusdc — an ESTIMATE that applies the last settled rate to your current position (negative = you would pay); the next rate is unknown until its boundary. next_boundary_ns is the next 8 h grid instant. Requires a credential.
No parameters.
Returns. instruments[] (net_uusdc_24h / _7d / _all, boundaries, last_payment_uusdc, last_boundary_ns, position_qty_now, mark_uusdc, last_rate_fp8, predicted_next_uusdc, next_boundary_ns), the account totals net_uusdc_24h and predicted_next_uusdc, next_boundary_ns, engine_seq_applied, and estimate_note.
Wraps. get-funding-summary
get_deadman
Get dead-man switch · read-only, idempotent
Whether the account's dead-man switch is armed, its TTL and expiry, and how often it has fired. Requires a credential.
No parameters.
Returns. armed, ttl_ms, expires_at_ns, fired_count, last_fired_at_ns.
Wraps. get-deadman
Write (credential)
Require a credential with the trade entitlement. Orders are two-phase: stage_order previews and returns a 60-second single-use confirm_token; place_order submits only with it.
stage_order
Stage an order (preview + confirm token) · read-only, idempotent
Preview an order without submitting it: book walk and expected execution, taker/maker fee estimate, total cost and breakeven, margin impact (IM delta, free collateral after), admission mirror (would_reject) and warnings. Returns a confirm_token valid 60 s and bound to these exact fields — pass it to place_order to submit. Nothing rests or fills. Requires a credential.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | yes | — | |
side | yes / no | yes | — | event contracts: yes | no; margined instruments: yes (the API's single side) |
action | buy / sell | yes | — | |
order_type | limit / market | no | "limit" | margined books accept limit only |
count | integer (> 0) | yes | — | contracts |
price_pips | integer | no | — | required for limit orders: event 1–9999; margined = signed ticks |
max_cost | integer (> 0) | no | — | market buys only: spend cap in atomic µUSDC |
tif | gtc / ioc / fok | no | — | |
sub_account_id | integer (min 0) | no | — | 0 = spot (event contracts), 1 = margin (perps/futures) |
reduce_only | boolean | no | — | |
post_only | boolean | no | — | |
stp_qualifier | string | no | — | self-trade prevention qualifier |
Returns. The venue preview: book (walk), execution (expected fills / resting remainder), fees (maker_fee_rate_bps, taker_fee_rate_bps, est_taker_fee_uusdc, est_maker_fee_uusdc, est_total_cost_uusdc, breakeven_pips), margin (im_delta, im_held_after, free_collateral_after, utilization_after_bps, position_if_filled; null for event contracts), would_reject (admission mirror or null), warnings[], and confirm_token with confirm_expires_at_ns.
Wraps. stage-order
place_order
Place a staged order · —
Submit an order previously staged with stage_order. Send the SAME fields plus its confirm_token (single-use, 60 s); a token bound to different fields is rejected with confirm_token_invalid. Returns the engine outcome: accepted_rested | accepted_fully_filled | accepted_ioc_canceled | rejected (+ reject_reason). If the credential's approval_mode is require_human the order is NOT submitted: the result is status pending_approval with a pending_id, and a human approves it in the terminal within 15 minutes (poll get_pending_orders). The credential's scope (instrument allowlist, per-order and daily notional caps, open-orders cap) is enforced first — see get_limits. client_order_id makes retries idempotent for ~15 minutes. Requires a credential with the TRADE entitlement.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | yes | — | |
side | yes / no | yes | — | event contracts: yes | no; margined instruments: yes (the API's single side) |
action | buy / sell | yes | — | |
order_type | limit / market | no | "limit" | margined books accept limit only |
count | integer (> 0) | yes | — | contracts |
price_pips | integer | no | — | required for limit orders: event 1–9999; margined = signed ticks |
max_cost | integer (> 0) | no | — | market buys only: spend cap in atomic µUSDC |
tif | gtc / ioc / fok | no | — | |
sub_account_id | integer (min 0) | no | — | 0 = spot (event contracts), 1 = margin (perps/futures) |
reduce_only | boolean | no | — | |
post_only | boolean | no | — | |
stp_qualifier | string | no | — | self-trade prevention qualifier |
confirm_token | string | yes | — | from stage_order |
client_order_id | string | no | — |
Returns. The engine outcome: order_id, status (accepted_rested / accepted_fully_filled / accepted_ioc_canceled / rejected), filled_count, resting_count, reject_reason when rejected, the echoed order fields, client_order_id, and the three latency timestamps — or, for a require_human credential, status: pending_approval with pending_id, notional_uusdc and expires_at_ns (nothing rests until a human approves).
Wraps. place-order
cancel_order
Cancel an order · destructive, idempotent
Cancel one resting order by order_id. Requires a credential.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
order_id | integer (> 0) | yes | — |
Returns. order_id, status: canceled, sequencer_correlation_id.
Wraps. cancel-order
cancel_all_orders
Cancel all orders · destructive, idempotent
Sweep every resting order on one instrument, or — when instrument_id is omitted — on EVERY instrument for the account. Asynchronous: returns an estimated count; completion arrives on the account WebSocket channel. Destructive. Requires a credential.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
instrument_id | integer (> 0) | no | — | omit for account-wide |
Returns. status: accepted, scope (instrument / account), estimated_count, sequencer_correlation_id; account scope adds mass_cancels[]. Completion arrives on the account WebSocket channel.
Wraps. cancel-all
set_deadman
Arm or refresh the dead-man switch · destructive, idempotent
Arm (or refresh) the account's dead-man switch: if it is not refreshed within ttl_ms (1000–300000) the venue cancels every resting order account-wide, once. ttl_ms = 0 disarms. Refresh it on every decision loop so a crashed agent cannot leave orders behind. Requires a credential.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
ttl_ms | integer (min 0, max 300000) | yes | — |
Returns. The new dead-man state (as get_deadman).
Wraps. set-deadman
Resources
Static-ish documents an MCP client can attach as context.
| URI | Title | Description |
|---|---|---|
sphx://reject-codes | Order reject, cancel reject and Edge error codes | Every code the venue emits with meaning and next action. |
sphx://markets | Market catalog | All listed instruments (same rows as list_markets with state=all). |
sphx://api | API reference pointers | Where the full REST/WebSocket reference lives. |