> For the complete documentation index, see [llms.txt](https://docs.symm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.symm.io/liquidity-provider-documentation/building-a-solver-on-symmio/instant-trading/instant-trading-api-template.md).

# 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:

```json
{
  "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:

```json
{
  "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
[
  {
    "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:

```json
{
  "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:

```json
{
  "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.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.symm.io/liquidity-provider-documentation/building-a-solver-on-symmio/instant-trading/instant-trading-api-template.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.