# nexus-xyz/nexus-exchange-rs architecture

> Architecture diagram of the GitHub repository nexus-xyz/nexus-exchange-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nexus-xyz/nexus-exchange-rs
- Repository: https://github.com/nexus-xyz/nexus-exchange-rs

## Overview

nexus-exchange is an official Rust SDK for Nexus Exchange, wrapping its REST API and two distinct WebSocket protocols. The main workflow is an application configuring a client, making public or authenticated market/account/trading requests, then consuming typed results or live events. Signed calls use the authentication abstractions; cursor-based list calls can be paged lazily. The sampled source confirms these boundaries, but does not expose every endpoint implementation, so the graph keeps REST capabilities grouped rather than inferring internal route-to-route calls.

Main entry points: [`src/client.rs`](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/client.rs) (HTTP client), [`src/ws/typed.rs`](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ws/typed.rs) (Typed subscriptions), [`src/rest.rs`](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/rest.rs) (REST endpoints), [`src/rest/pagination.rs`](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/rest/pagination.rs) (Cursor pagination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_rest["REST endpoints<br/>[rest.rs]"]
  node_markets["Market utilities<br/>[markets.rs]"]
  node_pagination["Cursor pagination<br/>[pagination.rs]"]
end

subgraph group_auth["Authentication"]
  node_credentials["API credentials<br/>[mod.rs]"]
  node_agent["Agent signing<br/>[agent.rs]"]
  node_eth["Wallet signing<br/>[eth.rs]"]
end

subgraph group_streaming["Streaming"]
  node_marketstream["Market stream<br/>[stream.rs]"]
  node_ws["Account WebSocket<br/>[ws.rs]"]
  node_typedws["Typed subscriptions<br/>[typed.rs]"]
  node_protocol["WS protocol<br/>[protocol.rs]"]
  node_backoff["Reconnect backoff<br/>[backoff.rs]"]
end

subgraph group_core["Client core"]
  node_client["HTTP client<br/>[client.rs]"]
  node_config["Network config<br/>[config.rs]"]
  node_ratelimit["Rate limiting<br/>[ratelimit.rs]"]
  node_models["Typed models<br/>[types.rs]"]
end

node_app(("SDK caller"))
node_exchange{{"Nexus REST API"}}
node_wsservice{{"Nexus WebSocket API"}}

node_app -->|"configures"| node_client
node_app -->|"requests data"| node_rest
node_app -->|"opens stream"| node_marketstream
node_app -->|"subscribes"| node_typedws
node_rest -->|"sends requests"| node_client
node_client -->|"uses settings"| node_config
node_client -->|"signs requests"| node_credentials
node_client -->|"paces requests"| node_ratelimit
node_client -->|"sends HTTP"| node_exchange
node_exchange -->|"returns responses"| node_client
node_rest -->|"builds pagers"| node_pagination
node_pagination -->|"fetches pages"| node_client
node_rest -->|"uses rounding"| node_markets
node_eth -->|"returns signed bodies"| node_app
node_agent -->|"provides signatures"| node_client
node_marketstream -->|"connects publicly"| node_wsservice
node_ws -->|"connects privately"| node_wsservice
node_typedws -->|"encodes and decodes"| node_protocol
node_typedws -->|"mints stream token"| node_client
node_typedws -->|"retries connections"| node_backoff
node_typedws -->|"subscribes"| node_wsservice
node_wsservice -->|"delivers events"| node_typedws
node_exchange -.->|"JSON follows types"| node_models

click node_client "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/client.rs"
click node_config "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/config.rs"
click node_ratelimit "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ratelimit.rs"
click node_models "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/types.rs"
click node_rest "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/rest.rs"
click node_markets "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/markets.rs"
click node_pagination "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/rest/pagination.rs"
click node_credentials "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/auth/mod.rs"
click node_agent "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/auth/agent.rs"
click node_eth "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/auth/eth.rs"
click node_marketstream "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/stream.rs"
click node_ws "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ws.rs"
click node_typedws "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ws/typed.rs"
click node_protocol "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ws/protocol.rs"
click node_backoff "https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ws/backoff.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rest,node_markets,node_pagination toneBlue
class node_credentials,node_agent,node_eth toneAmber
class node_marketstream,node_ws,node_typedws,node_protocol,node_backoff,node_exchange,node_wsservice toneMint
class node_client,node_config,node_ratelimit,node_models toneRose
class node_app toneIndigo
```

## Components

### REST API

- [REST endpoints](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/rest.rs): `src/rest.rs`
- [Market utilities](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/markets.rs): `src/markets.rs`
- [Cursor pagination](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/rest/pagination.rs): `src/rest/pagination.rs`

### Authentication

- [API credentials](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/auth/mod.rs): `src/auth/mod.rs`
- [Agent signing](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/auth/agent.rs): `src/auth/agent.rs`
- [Wallet signing](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/auth/eth.rs): `src/auth/eth.rs`

### Streaming

- [Market stream](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/stream.rs): `src/stream.rs`
- [Account WebSocket](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ws.rs): `src/ws.rs`
- [Typed subscriptions](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ws/typed.rs): `src/ws/typed.rs`
- [WS protocol](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ws/protocol.rs): `src/ws/protocol.rs`
- [Reconnect backoff](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ws/backoff.rs): `src/ws/backoff.rs`

### Client core

- [HTTP client](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/client.rs): `src/client.rs`
- [Network config](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/config.rs): `src/config.rs`
- [Rate limiting](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/ratelimit.rs): `src/ratelimit.rs`
- [Typed models](https://github.com/nexus-xyz/nexus-exchange-rs/blob/main/src/types.rs): `src/types.rs`

### Other components

- **SDK caller**
- **Nexus REST API**
- **Nexus WebSocket API**

## Connections

- SDK caller → HTTP client: configures
- SDK caller → REST endpoints: requests data
- SDK caller → Market stream: opens stream
- SDK caller → Typed subscriptions: subscribes
- REST endpoints → HTTP client: sends requests
- HTTP client → Network config: uses settings
- HTTP client → API credentials: signs requests
- HTTP client → Rate limiting: paces requests
- HTTP client → Nexus REST API: sends HTTP
- Nexus REST API → HTTP client: returns responses
- REST endpoints → Cursor pagination: builds pagers
- Cursor pagination → HTTP client: fetches pages
- REST endpoints → Market utilities: uses rounding
- Wallet signing → SDK caller: returns signed bodies
- Agent signing → HTTP client: provides signatures
- Market stream → Nexus WebSocket API: connects publicly
- Account WebSocket → Nexus WebSocket API: connects privately
- Typed subscriptions → WS protocol: encodes and decodes
- Typed subscriptions → HTTP client: mints stream token
- Typed subscriptions → Reconnect backoff: retries connections
- Typed subscriptions → Nexus WebSocket API: subscribes
- Nexus WebSocket API → Typed subscriptions: delivers events
- Nexus REST API → Typed models: JSON follows types