> For the complete documentation index, see [llms.txt](https://docs.unix.market/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unix.market/conventions/request-and-response-format.md).

# 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 endpoint-specific business fields plus shared public parameters used for signing and permission checks. The individual endpoint pages list the business fields; the shared public parameters below apply to signed writes.

| Field group         | Detail                                                                                        |
| ------------------- | --------------------------------------------------------------------------------------------- |
| Business parameters | Endpoint-specific fields, such as order, cancel, leverage, or Agent authorization parameters. |
| Public parameters   | Shared fields used to build or verify the signed payload.                                     |

| Public parameter | Type    | Required | Participates in signing?    | Detail                                                                                                                                                                       |
| ---------------- | ------- | :------: | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signer_address` | string  |    Yes   | Yes                         | Signer address. It can be a user wallet address or an Agent Key address. The node recovers the signer from `signature` and rejects the request unless it matches this value. |
| `target_address` | string  |    No    | When present, Method A only | Target account for this operation. If omitted, the target defaults to `signer_address`. Method B does not use this field.                                                    |
| `nonce`          | integer |    Yes   | Yes                         | Millisecond timestamp, tracked per `signer_address`.                                                                                                                         |
| `expires_after`  | integer |    Yes   | Yes                         | Request expiration timestamp in milliseconds.                                                                                                                                |
| `signature`      | object  |    Yes   | No                          | ECDSA signature result `{ r, s, v }`.                                                                                                                                        |
| `signature.r`    | string  |    Yes   | No                          | 32-byte hex string with `0x` prefix.                                                                                                                                         |
| `signature.s`    | string  |    Yes   | No                          | 32-byte hex string with `0x` prefix.                                                                                                                                         |
| `signature.v`    | integer |    Yes   | No                          | Recovery identifier, `27` or `28`.                                                                                                                                           |

The client computes `signing_hash` using the endpoint's signing method, signs it with the private key for `signer_address`, then submits the resulting `signature` object in the request body.

See [Signing Method A](broken://pages/f4565102d89fcb257b28b8bfa4ed2884ab2b4203) and [Signing Method B](broken://pages/4fab8cbb6c55356fc351c28f14c6d6e005b96414) 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](broken://pages/33bf243d7ec6ed169a076cfa9458553b9649be38). |
| `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": ""
}
```

> Determine success by checking `code == "0"`. `trace_code` is for support diagnostics only — clients should not parse it.


---

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

```
GET https://docs.unix.market/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.