> For the complete documentation index, see [llms.txt](https://docs.reya.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reya.xyz/developers/getting-started/readme.md).

# Introduction

Trading clients. Market data. Applications built on Reya.

<figure><img src="https://2401164987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyKdkzyUuAy6ZI0twu6yj%2Fuploads%2Fgit-blob-32b73f769fa47cc6e474e51f2a636655222d538d%2Fdeveloper-hero.webp?alt=media" alt=""><figcaption></figcaption></figure>

Build trading clients, market-data tools, dashboards, and automated strategies on Reya's perpetual and spot order book. Connect to the exchange. Stream the market. Make it yours.

{% hint style="info" %}
This guide covers the order book on Reya mainnet, documenting API **3.6.2**. Use devnet1 for integration testing; see [Environments](/developers/getting-started/environments.md). [Under Development](/developers/under-development/whats-next.md) lists features that are not yet available.
{% endhint %}

## Get started

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Quickstart</strong></td><td>Read market data, configure an account and signer, submit an order, and track its execution.<br><br><strong>Start building →</strong></td><td><a href="/developers/getting-started/onboarding.md">Quickstart</a></td></tr><tr><td><strong>Test on devnet1</strong></td><td>Use the same API against devnet1 before going live. Endpoints, chain IDs and contracts for both environments.<br><br><strong>See environments →</strong></td><td><a href="/developers/getting-started/environments.md">Environments</a></td></tr></tbody></table>

## From first request to first order

Start with a public market-data request on **mainnet**. No account or signer is needed for this step.

{% code title="Read perpetual market definitions · mainnet" %}

```bash
curl --fail --silent --show-error \
  https://api.reya.xyz/v2/perpMarketDefinitions
```

{% endcode %}

The response describes the available perpetual markets. Follow the [Quickstart](/developers/getting-started/onboarding.md) to configure an account and signer, submit an order, and track its execution.

## Your integration toolkit

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>REST API</strong></td><td>Discover markets, manage orders, and query account data.</td><td><a href="/developers/api-reference/rest-api-reference.md">REST API Reference</a></td></tr><tr><td><strong>WebSocket feeds</strong></td><td>Stream order-book updates, order changes, and executions.</td><td><a href="/developers/api-reference/websocket-api-reference.md">WebSocket Info API Reference</a></td></tr><tr><td><strong>Python SDK</strong></td><td>Get started with the Python SDK and working examples.</td><td><a href="https://github.com/Reya-Labs/reya-python-sdk/tree/v3.6.1.0">https://github.com/Reya-Labs/reya-python-sdk/tree/v3.6.1.0</a></td></tr></tbody></table>

## What Reya is

Reya runs a **central-limit order book for perpetual futures and spot**, matched by an **off-chain matching engine (ME)** and settled on **Reya Network**, an Ethereum L2. It is a **hybrid system**: matching is fast and off-chain, while every resulting trade is independently validated and settled on-chain. The chain is always the ultimate source of truth.

Concretely, as an integrator you:

1. **Sign** each order as an EIP-712 `OrderDetails` payload with your trading wallet. (See [Signatures & Nonces](/developers/authentication/signatures-and-nonces.md).)
2. **Submit** it over [REST](/developers/api-reference/rest-api-reference.md) or the [WebSocket Order Entry API](/developers/api-reference/ws-exec-api-reference.md) — both carry the same payloads and signing rules.
3. The **ME matches** your order against the book and produces fills.
4. Reya **validates each fill for on-chain settlement**.
5. **Track the settlement outcome** and reconcile order state and fills over the [WebSocket Info API](/developers/api-reference/websocket-api-reference.md), and handle the rare [trade bust](/developers/executions-and-settlement/trade-busts.md) when on-chain settlement rejects a match.

## Both perp and spot go through the same path

Perpetual and spot orders share one order-entry surface, one matching engine, and one settlement path. They differ only in the market they target and in a few settlement details. Where the two diverge — for example the `marketId` namespace (see [Market IDs](/developers/reference/market-ids.md)), or the `perpExecutions` vs `spotExecutions` channels — the relevant page calls it out explicitly.

## How these docs are organised

* **Getting Started** — [quickstart](/developers/getting-started/onboarding.md) (read market data and submit your first order), the [environments](/developers/getting-started/environments.md) and their URLs, the [account model](/developers/getting-started/accounts-and-subaccounts.md), and [signer authorization](/developers/getting-started/signer-authorization.md).
* **Connectivity** — [where the ME lives and how to connect](/developers/connectivity/connecting-to-the-matching-engine.md), plus [heartbeats](/developers/connectivity/heartbeats.md).
* **Authentication** — the [EIP-712 signing recipe and nonce strategy](/developers/authentication/signatures-and-nonces.md).
* **API Reference** — the [REST](/developers/api-reference/rest-api-reference.md), [WebSocket Order Entry](/developers/api-reference/ws-exec-api-reference.md), and [WebSocket Info](/developers/api-reference/websocket-api-reference.md) references.
* **Order Entry** — [order types & time-in-force](/developers/order-entry/order-types-and-tif.md), the [order lifecycle](/developers/order-entry/order-lifecycle.md), and [cancel-on-disconnect](/developers/order-entry/cancel-on-disconnect.md).
* **Executions & Settlement** — [trade settlement](/developers/executions-and-settlement/settlement.md), [trade busts](/developers/executions-and-settlement/trade-busts.md), and [executions & trade history](/developers/executions-and-settlement/executions-and-trade-history.md).
* **Pricing & Funding** — [oracle & index prices](/developers/pricing-and-funding/oracle-and-index-prices.md), the [mark price](/developers/pricing-and-funding/mark-price.md), and [funding](/developers/pricing-and-funding/funding.md).
* **Risk** — [liquidations & ADL](/developers/risk/liquidations-and-adl.md) and the [margin system](/developers/risk/margin-system.md).
* **Reference** — [market IDs](/developers/reference/market-ids.md), [markets & assets](/developers/reference/markets-and-assets.md), [fees](/developers/reference/fees.md), [contract addresses](/developers/reference/contract-addresses.md), [audits](/developers/reference/audits.md), and the [Python SDK 3.6.1.0](https://github.com/Reya-Labs/reya-python-sdk/tree/v3.6.1.0).

## Recommended starting path

If you're integrating for the first time, read in this order:

[Quickstart](/developers/getting-started/onboarding.md) → [Environments](/developers/getting-started/environments.md) → [Signatures & Nonces](/developers/authentication/signatures-and-nonces.md) → [REST API Reference](/developers/api-reference/rest-api-reference.md) → [Trade Settlement](/developers/executions-and-settlement/settlement.md) → [Trade Busts](/developers/executions-and-settlement/trade-busts.md).

The [Python SDK 3.6.1.0](https://github.com/Reya-Labs/reya-python-sdk/tree/v3.6.1.0) is the fastest way to get a correct signature end-to-end.

{% hint style="info" %}
This guide targets API **3.6.2**, preserved in the [pinned canonical spec source](https://github.com/Reya-Labs/reya-api-specs/tree/1fdb52a9ce50d2f2d52b28f2895a5f0be0c01e80). The REST and WebSocket spec downloads describe the API currently available at those endpoints, which may differ from this guide; see the [Changelog](/developers/changelog/changelog.md) for API changes.

The Python SDK links use release **3.6.1.0**, generated from API **3.6.1**. See [SDK installation](/developers/getting-started/onboarding.md#install-the-pinned-python-sdk) and [Handling ambiguous outcomes](/developers/connectivity/handling-ambiguous-outcomes.md).
{% endhint %}