# Request & Response Format

A small set of conventions applies to every endpoint.

## Request

| Rule              | Detail                                                         |
| ----------------- | -------------------------------------------------------------- |
| Content-Type      | `application/json`                                             |
| Field naming      | `snake_case`                                                   |
| Decimal values    | **String** (e.g. `"67500.00"`). Never use floats — they round. |
| Timestamps        | Integer Unix milliseconds (`uint64`).                          |
| Booleans          | JSON `true` / `false`.                                         |
| Addresses         | `0x`-prefixed 40-char hex, lowercase (e.g. `0xabc…def`).       |
| Omitted optionals | Simply do not include the key.                                 |

## Signed Request Parameters

Every write (`POST`) endpoint carries a shared signature envelope alongside its business fields. You construct it once and reuse the pattern on every write — the individual endpoint pages list only their business fields.

| Field            |   Signed?   | Detail                                                                                                                                                                                                                                |
| ---------------- | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address`        |      ✅      | Signer's address. The node verifies it against the `ecrecover` result.                                                                                                                                                                |
| `nonce`          |      ✅      | Millisecond timestamp, tracked **per signer**.                                                                                                                                                                                        |
| `expires_after`  |      ✅      | Expiration timestamp (ms).                                                                                                                                                                                                            |
| `target_address` | conditional | Only when an Agent operates on a sub-account. When present it enters the EIP-712 `Agent` struct (6-field variant) but **not** the `actionHash`. Private-key-only endpoints (Agent management, sub-account creation) do not accept it. |
| `signature`      |      —      | The ECDSA signature `{ r, s, v }` itself.                                                                                                                                                                                             |

See [Signing Method A](file:///1548985/authentication-and-signing/signing-method-a.md) and [Signing Method B](file:///1548985/authentication-and-signing/signing-method-b.md) for how the envelope is built.

## Response Envelope

Every endpoint returns the same envelope. `code`, `msg`, and `data` are always present. Each endpoint's reference page documents only the contents of `data`.

| Field        | Type           | Detail                                                                                                         |
| ------------ | -------------- | -------------------------------------------------------------------------------------------------------------- |
| `code`       | string         | `"0"` = success. Non-zero is an error code — see [Error Codes](file:///1548985/reference/error-code-index.md). |
| `msg`        | string         | Empty on success; human-readable description on failure.                                                       |
| `data`       | object \| null | Endpoint-specific payload on success; `null` on failure.                                                       |
| `trace_code` | string         | Backend trace identifier. Empty on success; populated on failure for support diagnostics.                      |

```json
{
  "code": "0",
  "msg": "",
  "data": { "order_id": "144115188075855872", "client_order_id": "my-order-1" },
  "trace_code": ""
}
```

{% hint style="info" %}
Determine success by checking `code == "0"`. `trace_code` is for support diagnostics only — clients should not parse it.
{% endhint %}

## Common Pitfalls

| Pitfall                                        | Fix                                                                                       |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Float JSON numbers for price / quantity        | Always use strings.                                                                       |
| Upper-case hex addresses                       | Lower-case only.                                                                          |
| Missing `address` on a write request           | Required even when the signer matches; the node uses it to verify the `ecrecover` result. |
| Wrong canonical-JSON key order for Method A    | Sort keys alphabetically.                                                                 |
| Same `nonce` reused across concurrent requests | Each request needs a unique ms. Use a counter or `Date.now()` plus a small offset.        |


---

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

```
GET https://docs.lynxtrade.world/conventions/request-and-response-format.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.