> For the complete documentation index, see [llms.txt](https://docs.sidepit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sidepit.com/users-and-agents/api/wire-protocol.md).

# Wire Protocol

Sidepit's current public NNG and protobuf surface.

The canonical contract is [`Public-API-Data/sidepit_api.proto`](https://github.com/sidepit/Public-API-Data/blob/main/sidepit_api.proto). This page describes only fields present in that public file.

## Port map

|    Port | NNG pattern | Public payload or action                             |
| ------: | ----------- | ---------------------------------------------------- |
| `12121` | Push        | Submit signed `SignedTransaction` orders and cancels |
| `12122` | Sub         | `MarketData`: quote, in-progress bar, and depth      |
| `12123` | Sub         | `TxBlockStream`: epoch echo clock                    |
| `12124` | Sub         | `OrderData`: book changes, fills, and margin states  |
| `12125` | Req/Rep     | `RequestReply` queries and signed account actions    |
| `12126` | Sub         | `EpochOrders`: advanced auction stream               |
| `12127` | Sub         | Closed one-minute `EpochBar` values                  |
| `12128` | Sub         | `RejectedTransaction`                                |
| `12129` | Sub         | Full open-order snapshot triggered through `12125`   |

## Identity and signing

`sidepit_id` is the owner's full Native SegWit `bc1q` address. In delegated mode, `agent_id` is the full address derived from the signing agent's compressed public key.

The signing sequence is:

1. populate the complete `Transaction`, including a strictly increasing nanosecond timestamp;
2. serialize it with protobuf;
3. SHA-256 hash the serialized bytes;
4. create a compact 64-byte secp256k1 ECDSA signature and hex-encode it; and
5. wrap it in `SignedTransaction` with `signature_version=0`.

The deterministic order ID is `{sidepit_id}:{timestamp_ns}`. Addresses, order IDs, and Bitcoin transaction IDs are carried in full.

## Order semantics

`NewOrder` contains side, size, price, and ticker. A missing/default `price=0` means native market intent. The engine normalizes it toward the opposite band edge for the sweep, then cancels all residual quantity before it can rest. An explicit nonzero price at a band edge remains a limit and may rest.

Port `12124` can publish more than one `OrderData` message per epoch. Messages identify their ticker, and `more_in_epoch == 0` marks the completed epoch.

## Account and execution fee state

`TraderPositionOrders.accountstate` contains `AccountMarginState`, including balances, `available_margin`, `pending_unlock`, `active_delegates`, and contract margins. `PositionMargin.realized_fees` carries execution fees accumulated by the engine at account and ticker scope.

The production constant is `execution_fee_sats_per_contract_per_side = 125`. It is deducted for every filled contract from each participant on each execution.

## Unlock records

`Transaction.unlock_req` carries explicit or MAX intent. Point-in-time account data exposes receipts and `AccountOperations.unlock_records`, whose public enum includes:

* `UNLOCK_PENDING`
* `UNLOCK_REJECTED`
* `UNLOCK_RESERVED`
* `UNLOCK_PROCESSING`
* `UNLOCK_COMPLETED`

`UnlockRecord` also carries the full operation ID, amount, Bitcoin transaction ID, and status update map. Terminal records and current account state are truth; an old pending receipt cannot override them.

## Rejects

Reject codes are named enum values, including `RC_VERIFY`, `RC_DUP`, `RC_ID`, `RC_BAD`, `RC_MARGIN`, and `RC_DK`. Cancel flows may also produce `RC_CDUP` or `RC_CREJ` when the target is already gone.


---

# 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.sidepit.com/users-and-agents/api/wire-protocol.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.