Instant Trading API Template

In scope

This template is for the client-facing instant trading system.

Routes:

Area	Routes
Signing config	GET /instant_trade/eip712-config
Trade submit	POST /instant_trade/instant_open, POST /instant_trade/instant_close
Pending and reconciliation	GET /instant_open/:account_address, GET /instant_close/:account_address, GET /temp_quote_status/:temp_quote_id, GET /instant_quote_id/:temp_quote_id
Error reference	GET /error_codes

Out of scope for this shared template:

• admin-only routes

• solver-specific operational endpoints

• internal worker flow

• hedging implementation details

If a solver has extra endpoints, they should be separate from this shared contract.

---

Model

1. Instant trading is asynchronous

• POST /instant_trade/instant_open accepts a request and returns a temporary tracking id.

• POST /instant_trade/instant_close accepts one or more close requests.

• Final execution may happen later in the solver background flow.

The client must not assume that 200 OK means the on-chain trade is already finalized.

2. Open and close use different identifiers

• Open starts without a protocol quote_id.

• The solver returns a solver-local temp_quote_id.

• The client later resolves that temp id into the final protocol quote_id.

• Close always refers to an existing protocol quote_id.

3. quote_id is the canonical cross-system identifier

• temp_quote_id is only for tracking an open request before final quote creation.

• quote_id is the long-term identifier for close, history, and reconciliation.

4. Public shape must be shared, internals may differ

Different solvers may use different:

• hedgers

• liquidity checks

• balance checks

• background job systems

• inventory integrations

Those differences must not change the API contract below.

---

Required endpoints

GET /instant_trade/eip712-config

Returns the EIP-712 config that clients must use for signing.

Expected top-level fields:

• domain

• domainSeparator

• typeHashes

• types

Optional extra fields are allowed, but these top-level fields should exist across solvers.

POST /instant_trade/instant_open

Request shape:

{
  "sendQuote": {
    "signedOperation": {},
    "signature": "0x..."
  },
  "addMargin": {
    "signedOperation": {},
    "signature": "0x..."
  }
}

Rules:

• sendQuote is required.

• addMargin is optional.

• The route must accept the same JSON shape even if a solver handles margin internally in a different way.

Success response:

{
  "temp_quote_id": -123,
  "partyBmm": "0"
}

Contract notes:

• temp_quote_id should be returned on every successful open submission.

• partyBmm should remain present for compatibility, even if fixed or unused by a solver.

POST /instant_trade/instant_close

Request shape:

[
  {
    "signedOperation": {},
    "signature": "0x..."
  }
]

Rules:

• The wire format is a JSON array.

• Each item represents one close operation.

• A solver may support one or many items, but the request shape should stay the same.

Success response:

• 200 OK with empty body is acceptable.

GET /instant_open/:account_address

Returns pending open requests for the given account.

Expected item shape:

[
  {
    "position_type": 0,
    "temp_quote_id": -123,
    "symbol_id": 1,
    "requested_open_price": "100.0",
    "quantity": "1.0",
    "party_a_address": "0x...",
    "cva": "0",
    "partyAmm": "0",
    "partyBmm": "0",
    "lf": "0",
    "order_type": 1
  }
]

Solvers may have different internal fields, but this shared response shape should stay stable.

GET /instant_close/:account_address

Returns pending close requests for the given account.

Expected item shape:

[
  {
    "quote_id": 42,
    "quantity_to_close": "1.0",
    "close_price": "100.0"
  }
]

GET /temp_quote_status/:temp_quote_id

Returns the current solver-side status for an open request.

Expected fields:

• state

• quote_id

• symbol_id

• position_type

• quantity

• price

Additional fields are allowed, but these should remain stable across solvers where possible.

Recommended response:

{
  "state": "pending",
  "quote_id": null,
  "symbol_id": 1,
  "position_type": 0,
  "quantity": "1.0",
  "price": "100.0"
}

GET /instant_quote_id/:temp_quote_id

Resolves a temp open id to the final protocol quote id.

Success response:

{
  "quote_id": 42
}

GET /error_codes

Returns the solver's stable error code mapping.

This route should exist so frontend and integrators can build consistent error handling without hardcoding one solver's private assumptions.

---

Conventions

Temp quote id

• temp_quote_id should be solver-local.

• It should be safe for the client to store and poll.

• It should not be reused as a replacement for quote_id.

• This field may later be replaced by a frontend-provided UUID if frontend and solver teams agree on a shared tracking identifier. Until then, clients should treat temp_quote_id as the temporary open-tracking key in this contract.

Account path parameter

• :account_address should represent the user subaccount.

State meaning

At minimum, solvers should use states with the same public meaning:

• pending: accepted by API, not finalized yet

• completed: successfully processed

• failed: rejected after submission or failed during processing

• cancelled: explicitly cancelled before completion

Exact internal state machines may be richer, but the public contract should map to these meanings clearly.

---