}
}'
```
You can query any pending or past withdrawals by:
```bash
curl -X 'GET' \
'https://api.ethereal.trade/v1/token/withdraw?subaccountId=45783bec-4675-4116-8829-f277afe063d7&orderBy=createdAt' \
-H 'accept: application/json'
```
```json
{
"hasNext": false,
"data": [
{
"id": "34510374-0010-4630-9954-46bb196806b2",
"initiatedBlockNumber": "11272338",
"finalizedBlockNumber": "11272403",
"status": "COMPLETED",
"subaccount": "0x7072696d61727900000000000000000000000000000000000000000000000000",
"token": "0xa1623E0AA40B142Cf755938b325321fB2c61Cf05",
"amount": "9",
"digest": "0x...",
"createdAt": 1743812502148
}
]
}
```
Once relayed onchain and after the lockout period has past, users can finalize their withdrawal:
```solidity
/// @notice Actions pending withdraw for a subaccount.
/// @notice WUSDe will be withdrawn as USDe regardless of whether it was originally deposited as WUSDe or USDe.
/// @param account Address of the account to perform on behalf of
/// @param withdrawDigest EIP712 digest of the withdraw data
function finalizeWithdraw(address account, bytes32 withdrawDigest) external;
```
{% hint style="success" %}
An offchain withdraw claimer automatically finalizes withdrawals on users behalf but using the digest a user is always able to `finalizeWithdraw()` without the claimer.
{% endhint %}
## Retrieve Transfer History
To view all historical transfers for a specific subaccount, query:
```bash
curl -X 'GET' \
'https://api.ethereal.trade/v1/token/transfer?subaccountId=45783bec-4675-4116-8829-f277afe063d7&statuses=COMPLETED&orderBy=createdAt' \
-H 'accept: application/json'
```
```json
{
"hasNext": false,
"data": [
{
"id": "34510374-0010-4630-9954-46bb196806b2",
"initiatedBlockNumber": "11272338",
"finalizedBlockNumber": "11272403",
"status": "COMPLETED",
"subaccount": "0x7072696d61727900000000000000000000000000000000000000000000000000",
"token": "0xa1623E0AA40B142Cf755938b325321fB2c61Cf05",
"type": "WITHDRAW",
"amount": "9",
"createdAt": 1743812502148,
"initiatedTransactionHash": "0xe21b386030fcbc1ff6948aac02e9e83db150e03ef9d2383c2a579d42be055a2b",
"finalizedTransactionHash": "0xe0b33c8e92f164b9bf1114987a7712e30bafbba23490436f4cc5e7ff1a44b9d7"
},
{
"id": "8cfae486-714f-4731-85ca-1b5da32e3755",
"initiatedBlockNumber": "11272299",
"finalizedBlockNumber": "11272306",
"status": "COMPLETED",
"subaccount": "0x7072696d61727900000000000000000000000000000000000000000000000000",
"token": "0xa1623E0AA40B142Cf755938b325321fB2c61Cf05",
"type": "DEPOSIT",
"amount": "10.000000001",
"createdAt": 1743812469703,
"initiatedTransactionHash": "0x6729fd9d7a2e154aa3704849fb720c3ec2f10f3d145adc0290b43761e25aacef",
"finalizedTransactionHash": "0xf22706a0c292061e3e9d843acad98f33a96b8b7e70b3920da81c1d032f18295d"
},
{
"id": "2eb362ff-f317-4865-9bee-032b4caf0b0d",
"initiatedBlockNumber": "11205366",
"finalizedBlockNumber": "11205371",
"status": "COMPLETED",
"subaccount": "0x7072696d61727900000000000000000000000000000000000000000000000000",
"token": "0xa1623E0AA40B142Cf755938b325321fB2c61Cf05",
"type": "DEPOSIT",
"amount": "20000",
"createdAt": 1743745535947,
"initiatedTransactionHash": "0x4591653ab33603c934b9c3041edad1af779293f347ec71e2c89c0f8b22cfc8a5",
"finalizedTransactionHash": "0xa11fbd46d39d8249820619a91e81962e4922546b6a13ce453b0db2b5bc9e3c5d"
}
]
}
```
## Token Transfer Fees
Fees on transfers primarily serve to deter spam and minimize network congestion, rather than as a revenue source. Fee structures are configurable per token and may be adjusted over time.
Both deposit and withdrawals can be configured to charge fees (denomianted in native token units). As of writing right now, there are **zero deposit fees** however USDe is configured to charge **a nominal withdrawal fee of 2**.
# Supported Tokens
## Overview
Tokens represent the assets used within the exchange ecosystem. Their configuration is managed exclusively by the exchange, with careful controls for both virtual and concrete assets.
The exchange supports two primary types of tokens:
* **Concrete tokens**: These correspond to actual ERC20 assets on the blockchain, such as USDe. Concrete tokens have an associated onchain address and can be deposited to and withdrawn from the exchange.
* **Virtual tokens**: These tokens exist only within the exchange ecosystem and serve as the base asset for specific markets without being directly tradable. For example, in the SOLUSD perpetual market, SOL would be configured as a virtual token without an onchain address.
* **Token promotion**: Virtual tokens can be promoted to concrete tokens as the exchange evolves. For example, BTC and ETH will initially be configured as virtual tokens at launch since they cannot be traded directly (i.e., cannot be a quote asset and cannot be spot traded). When the exchange is upgraded to support spot trading and portfolio margin, the ETH virtual token can be promoted to a concrete token, enabling direct trading, deposits, and withdrawals.
{% hint style="info" %}
Ethereal will only support USDe concrete tokens on launch with BTC and ETH support in a subsequent release for portfolio margin.
{% endhint %}
## Why Virtual Tokens?
This design allows contracts and downstream offchain services reconcile tokens without branching deeply supporting non-tokens and tokens. Everything is simply a “token”. When necessary, a token can be promoted to a concrete token by providing an address.
### Configuration
Token management is handled through privileged contract functions:
* All token configuration functions are protected by `onlyOwner` modifiers
* The same configuration management processes control which tokens are acceptable for deposits
* Token management functions emit `TokenXXX` events (e.g., `TokenAdded`, `TokenUpdated`) that are indexed and propagated to offchain systems
Each token can have various settings that are managed independently:
* **Status flags**: deposit enabled/disabled, withdrawal enabled/disabled
* **Risk controls**: deposit caps (maximum amount that can be deposited), withdrawal limits
* **Fee structure**: Deposit/withdrawal fees
### Retrieving Configured Tokens
Once configured and indexed, you can query against the trading API to retrieve configured tokens:
```bash
curl -X 'GET' \
'https://api.ethereal.trade/v1/token?order=asc' \
-H 'accept: application/json'
```
```json
{
"hasNext": false,
"data": [
{
"id": "ff761c8b-6248-4673-b63d-d1f980551959",
"address": "0xa1623E0AA40B142Cf755938b325321fB2c61Cf05",
"name": "USD",
"erc20Name": "USDe",
"erc20Symbol": "USDe",
"erc20Decimals": 18,
"depositEnabled": true,
"withdrawEnabled": true,
"depositFee": "0",
"withdrawFee": "1",
"minDeposit": "10",
"createdAt": 1743745409966
},
{
"id": "d800d607-2c0d-43f6-af5e-19b7f8dd4caa",
"address": "0x0000000000000000000000000000000000000000",
"name": "BTC",
"depositEnabled": false,
"withdrawEnabled": false,
"depositFee": "0",
"withdrawFee": "0",
"minDeposit": "0",
"createdAt": 1743745409966
},
{
"id": "cda05e1e-fd10-433c-8cbd-36b7545307b0",
"address": "0x0000000000000000000000000000000000000000",
"name": "ETH",
"depositEnabled": false,
"withdrawEnabled": false,
"depositFee": "0",
"withdrawFee": "0",
"minDeposit": "0",
"createdAt": 1743745409966
},
{
"id": "790b743e-1a19-4bd6-8cd4-1bcff9bb0b86",
"address": "0x0000000000000000000000000000000000000000",
"name": "ENA",
"depositEnabled": false,
"withdrawEnabled": false,
"depositFee": "0",
"withdrawFee": "0",
"minDeposit": "0",
"createdAt": 1743745409966
}
}
```
{% hint style="info" %}
Concrete tokens will always have an ERC20 `address` .
{% endhint %}
Tokens are also accessible onchain:
```solidity
/// @notice Returns an array of token names.
function getExchangeTokens() external view returns (bytes32[] memory);
/// @notice Returns the token deatils, that was at one point supported by the exchange.
/// @param tokenName Name of the token to retrieve the details for
function getToken(bytes32 tokenName) external returns (Token.Data memory);
library Token {
struct Data {
/// Address of token (can be zero when virtual);
address tokenAddress;
/// Maximum balance an account can hold after a deposit.
uint256 depositCapacity;
/// Minimum deposits amount, in the token, in the native units.
uint256 minDeposit;
/// Withdraw fee, in the token, in the native units.
uint128 withdrawFee;
/// Deposit fee, in the token, in the native units.
uint128 depositFee;
/// Deposit restriction.
bool depositEnabled;
/// Withdraw restriction.
bool withdrawEnabled;
/// If the token is used by a product (as either a quote or base asset), it cannot never be removed.
bool removeProtected;
}
}
```
Tokens are not particularly useful on their own but they referenced throughout the trading API in areas such as transfers, products, and subaccount balances.
## Unit Precision
Ethereal implements a standardized precision approach for all supported tokens, maintaining consistent gwei precision (1e9 or 9 decimal places) throughout the exchange. This standardization ensures that tokens with more than 9 decimals (like USDe with 18 decimals) are downscaled, while tokens with fewer decimals are upscaled to match the uniform 9-decimal precision used internally.
When making deposits, users must specify amounts in the token's native precision relative to its original decimal places. For example, depositing 1000 USDe requires specifying 1000000000000 (1e18). However, once these tokens enter the exchange, they're automatically normalized to the standard 9-decimal precision used across all internal systems and calculations.
This normalized precision is consistently reflected throughout the platform, with API responses expressing token amounts as string decimals and message signing representing amounts as integers with 1e9 precision. This approach eliminates potential calculation errors that could arise from varying decimal places across different tokens and ensures reliable, consistent handling of all supported assets.
# WebSockets
The WebSocket gateway provides real-time streaming access to market data and trading updates on the Ethereal exchange. Clients subscribe to channels over a persistent connection and receive plain JSON payloads with short-form keys, optimized for low latency, minimal overhead, and fast parsing.
| URL | Status |
|---|
wss://ws2.ethereal.trade/v1/stream | Mainnet |
wss://ws2.etherealtest.net/v1/stream | Testnet |
wss://ws.ethereal.trade/v1/stream | Deprecated (Socketio) |
{% hint style="info" %}
Native WebSocket (v2) replaces socketio. Visit [Socket.io (deprecated)](/developer-guides/trading-api/websockets/socket.io-deprecated) for socket.io based streams.
{% endhint %}
### Subscription
The subscription gateway offers multiple data streams for real-time and periodic updates. Some channels e.g. `OrderUpdate` push messages immediately as they occur, while others e.g. `L2Book` emit messages at fixed intervals. Payload formats and message shapes are documented below.
#### Connection Behavior
Connections have a maximum lifetime of approximately **4 hours**, after which they are closed with ***code 1000***. Clients are encouraged to implement automatic reconnection to handle this.
Idle connections with no message activity between both parties are closed after a period of inactivity with ***code 1006***. It is the *responsibility of the client to send WebSocket ping frames periodically* to prevent idle disconnects (we recommend once every 30s).
{% code overflow="wrap" expandable="true" %}
```javascript
// Example client-side heartbeat (javascript)
const WebSocket = require("ws");
const ws = new WebSocket("wss://ws2.ethereal.trade/v1/stream");
let pingInterval;
ws.on("open", () => {
pingInterval = setInterval(() => {
if (ws.readyState === WebSocket.OPEN) {
ws.ping();
}
}, 30_000);
});
ws.on("close", () => {
clearInterval(pingInterval);
});
```
{% endcode %}
{% hint style="warning" %}
There is a per-connection limit on subaccount subscriptions.
Each `(subaccountId, streamType)` pair counts as one subscription. Market data channels (`L2Book`, `Ticker`, `TradeFill`) are not subject to this limit.
Exceeding the limit returns `{ ok: false, code: "SUBSCRIPTION_LIMIT_EXCEEDED" }`
{% endhint %}
#### `L2Book`
Provides L2 book depth updates for a specific product.
// Subscription message payload
{
"event": "subscribe",
"data": {
"type": "L2Book",
"symbol": "<string>" // e.g. "BTCUSD", "ETHUSD"
}
}
// Response message
{
"e": "L2Book",
"t": <epoch>,
"data": {
"s": "<string>",
"t": <epoch>,
"pt": Optional<epoch>,
"a": [[price: string, quantity: string]],
"b": [[price: string, quantity: string]]
}
}
**`L2_BOOK`** events are emitted on a configurable fixed interval (as of writing, this is configured to be *once every 200ms*).
* `e` - event name
* `t` - server timestamp (epoch in milliseconds)
* `data` - L2 Book price levels details
* `s` - symbol e.g. BTCUSD
* `t` - calculated book timestamp (epoch in milliseconds)
* `pt` - previous calculated book timestamp (epoch in milliseconds) - optional
* Using both the `pt` and `data.t` you can infer whether or not any events were missed during connection or during consumption
* `a` - asks, array of `[price, qty]` pairs
* `b` - bids, array of `[price, qty]` pairs
{% hint style="warning" %}
A `L2Book` message of the current book **(up to 100 price levels per side)** is emitted back as an initial snapshot on connection. Every subsequent message is a price level diff with absolute quantities. A zero quantity price diff indicates that this level has been removed.
{% endhint %}
#### `TICKER`
Delivers real-time ticker data feeds for a specified product.
{% code expandable="true" %}
```json
// Subscription message payload
{
"event": "subscribe",
"data": {
"type": "Ticker",
"symbol": "" // e.g. "BTCUSD", "ETHUSD"
}
}
// Response message
{
"e": "Ticker",
"t": ,
"data": {
"s": "",
"t": ,
"bidPx": "Optional",
"askPx": "Optional",
"bidAmt": "Optional",
"askAmt": "Optional",
"markPx": "Optional",
"markPx24h": "Optional",
"oi": "Optional",
"fr1h": "Optional",
"vol24h": "Optional"
}
}
```
{% endcode %}
**`TICKER`** events are emitted on a configurable fixed interval (currently configured to be *once every second*).
* `e` - event name `Ticker`
* `t` - server timestamp this message was emitted at (epoch in milliseconds)
* `data` - Real time ticker data
* `s` - symbol e.g. BTCUSD
* `t` - calculated best bid / ask book timestamp
* `bidPx` - best bid price
* `askPx` - best ask price
* `bidAmt` - total quantity at the best bid
* `askAmt` - total quantity at the best ask
* `markPx` - current mark price
* `markPx24h` - 24h mark price
* `oi` - open interest
* `fr1h` - projected funding rate at the end of the hour
* `vol24h` - past 24 hours volume
{% hint style="warning" %}
In extreme cases, **`Ticker`** will skip publishing if **both** **`bidPx`** & **`askPx`** are not available. All values are returned as decimals (9 precision).
{% endhint %}
#### `TRADE_FILL`
Provides a stream of trades that have occurred filtered by product.
```json
// Subscription message payload
{
"event": "subscribe",
"data": {
"type": "TradeFill",
"symbol": "" // e.g. "BTCUSD", "ETHUSD"
}
}
// Response message
{
"e": "TradeFill",
"t": ,
"data": {
"s": "",
"t": ,
"d":[{
"id": "",
"px": "",
"sz": "",
"sd": 0|1,
"sids": ["", ""]
}]
}
}
```
**`TRADE_FILL`** events are streamed in real-time as they occur and from the perspective of the taker (i.e. `sz`, `sd`).
* `e` - event name
* `t` - server timestamp this message was emitted at (epoch in milliseconds)
* `data`
* `s` - symbol of product traded
* `t` - timestamp trade fills happened (epoch in milliseconds)
* `d` - array of fills that occurred on the product
* `s` - symbol e.g. BTCUSD where the trade fill occurred on
* `id` - trade fill identifier
* `px` - execution price
* `sz` - quantity traded
* `sd` - side (`0=BUY` or `1=SELL`) from the perspective of the taker
* `sids` - tuple of the taker subaccount id and the maker subaccount id
#### `SUBACCOUNT_LIQUIDATION`
Provides an update when a subaccount is liquidated.
{% code expandable="true" %}
```json
// Subscription message payload
{
"event": "subscribe",
"data": {
"type": "SubaccountLiquidation",
"subaccountId": ""
}
}
// Response message
{
"e": "SubaccountLiquidation",
"t": ,
"data": {
"sid": "",
"t": ,
"d": [
{
"s": "",
"px": "",
"sz": ""
}
]
}
}
```
{% endcode %}
When a subaccount is liquidated, all positions are transferred to the insurance fund and derisked at a later time. `SubaccountLiquidation` events are emitted in real-time.
* `e` - event name
* `t` - server timestamp this message was emitted at (epoch in milliseconds)
* `data` - Liquidation subaccount data
* `sid` - `id` of liquidated sub-account
* `t` - timestamp sub-account was liquidated (epoch in miliseconds)
* `d` - An array of positions liquidated (subaccount may have one or many positions at liquidation):
* `price` - mark price at the time of liquidation
* `sz` - position size at liquidation (positive of long, negative if short)
#### **`POSITION_UPDATE`**
Provides real-time updates to open positions for a specific subaccount.
{% code overflow="wrap" expandable="true" %}
```json
// Subscription message payload
{
"event": "subscribe",
"data": {
"type": "PositionUpdate",
"subaccountId": ""
}
}
// Response message
{
"e": "PositionUpdate",
"t": ,
"data": {
"t": ,
"d": [
{
"id": "",
"sid": "",
"s": "",
"sd": 0|1,
"sz": "",
"cost": "",
"rpnl": "",
"fpnl": "",
"fee": "",
"lpx": "Optional"
}
]
}
}
```
{% endcode %}
**`POSITION_UPDATE`** events are emitted in real-time, published per-subaccount whenever a position is opened, increased/reduced, or closed.
* `e` - event name
* `t` - server timestamp (epoch in milliseconds)
* `data` - position update details
* `t` - update timestamp (epoch in milliseconds)
* `d` - array of position updates
* `id` - position ID (UUID)
* `sid` - subaccount ID (UUID)
* `s` - ticker symbol (e.g. ETHUSD or BTCUSD)
* `sd` - position side (BUY or SELL)
* `sz` - position size
* `cost` - position value in USD (`quantity * average entry price`)
* `rpnl` - realized PnL in USD
* `fpnl` - funding in USD (charged and applied to position, negative if paid)
* `fee` - fees accrued in USD
* `lpx` - liquidation price (only set if liquidated)
{% hint style="info" %}
Funding charges do not trigger `PositionUpdate` events.
{% endhint %}
#### **`ORDER_UPDATE`**
Provides updates about order status changes for a specific subaccount.
{% code expandable="true" %}
```json
// Subscription message payload
{
"event": "subscribe",
"data": {
"type": "OrderUpdate",
"subaccountId": ""
}
}
// Response message
{
"e": "OrderUpdate",
"t": ,
"data": {
"t": ,
"d": [
{
"id": "",
"cloid": "Optional",
"otyp": "LIMIT" | "MARKET",
"qty": "",
"aqty": "",
"fill": "",
"px": "Optional",
"sd": 0|1,
"s": "",
"sid": "",
"sn": "",
"st": "",
"t": ,
"ro": boolean,
"cl": boolean,
"tif": "Optional",
"et": ,
"po": Optional,
"spx": "Optional",
"styp": Optional,
"spxtyp": Optional,
"tr": "",
"gtyp": Optional,
"gid": "Optional",
"rr": "Optional"
}
]
}
}
```
{% endcode %}
**`ORDER_UPDATE`** events are emitted in real-time, published per-subaccount whenever an order's state changes.
* `e` - event name
* `t` - server timestamp (epoch in milliseconds)
* `data` - order update details
* `t` - update timestamp (epoch in milliseconds)
* `d` - array of order updates
* `id` - order ID (UUID)
* `cloid` - client order ID
* `otyp` - order type
* `qty` - original quantity
* `aqty` - available (remaining) quantity
* `fill` - filled amount
* `px` - limit price - optional, omitted for market orders
* `sd` - side (`BUY=0`, `SELL=1`)
* `s` - symbol e.g. BTCUSD
* `sid` - subaccount ID (UUID)
* `sn` - sender (signer EVM address)
* Account or linked signer address that originally placed this order
* `st` - order status (enum, same status as `OrderDto.status`)
* One of: `NEW, PENDING, FILLED_PARTIAL, FILLED, REJECTED, CANCELED, EXPIRED`
* `t` - order created timestamp (epoch in milliseconds)
* `ro` - reduce only (boolean)
* `cl` - close (boolean)
* `tif` - time in force
* `et` - expires at (epoch in seconds)
* `po` - post only
* `spx` - stop price
* `styp` - stop type
* `spxtyp` - stop price type
* `tr` - triggered state
* `gtyp` - group contingency type
* `gid` - group ID (UUID)
* `rr` - reason the order was rejected e.g. `CausesImmediateLiquidation`, `OrderIncreasesPosition`, `MarketOrderReachedMaxSlippage`, etc.
* See: `OrderDto.rejectedReason` for the full list of possible values
#### `ORDER_FILL`
Notifies when orders are filled for a specific subaccount.
{% code expandable="true" %}
```json
// Subscription message payload
{
"event": "subscribe",
"data": {
"type": "OrderFill",
"subaccountId": ""
}
}
// Response message
{
"e": "OrderFill",
"t": ,
"data": {
"t": ,
"d": [
{
"id": "",
"oid": "",
"cloid": "Optional",
"px": "",
"sz": "",
"typ": "LIMIT" | "MARKET",
"sd": 0|1,
"s": "",
"sid": "",
"ro": boolean,
"fee": "",
"m": boolean,
"t":
}
]
}
}
```
{% endcode %}
**`ORDER_FILL`** events are emitted in real-time as they occur, published per-subaccount whenever an order is filled (both maker and taker sides receive their own event).
* `e` - event name
* `t` - server timestamp (epoch in milliseconds)
* `data` - order fill details
* `t` - fill timestamp (epoch in milliseconds)
* `d` - array of order fills
* `id` - fill ID (UUID)
* `oid` - order ID (UUID)
* `cloid` - client order ID - optional
* `px` - fill price
* `sz` - filled quantity
* `typ` - order type
* `sd` - side
* `s` - symbol e.g. BTCUSD
* `sid` - subaccount ID (UUID)
* `ro` - reduce only
* `fee` - fee in USD
* `m` - is maker
* `t` - created at timestamp (epoch in milliseconds)
#### `TOKEN_TRANSFER`
Provides updates for deposits / withdrawals for a specific subaccount.
{% code expandable="true" %}
```json
// Subscription message payload
{
"event": "subscribe",
"data": {
"type": "TokenTransfer",
"subaccountId": ""
}
}
// Response message
{
"e": "TokenTransfer",
"t": ,
"data": {
"t": ,
"id": "",
"sid": "",
"tName": "",
"tAddr": "",
"typ": "",
"st": "",
"amt": "",
"fee": "",
"iniBk": "Optional",
"finBk": "Optional",
"iniTx": "Optional",
"finTx": "Optional",
"lzAddr": "Optional",
"lzEid": "Optional"
}
}
```
{% endcode %}
**`TOKEN_TRANSFER`** events are published per-subaccount when a deposit or withdrawal state changes.
* `e` - event name
* `t` - server timestamp this message was emitted at (epoch in milliseconds)
* `data` - token transfer details
* `id` - unique identifier of the transfer
* `t` - timestamp token transfer event (epoch in miliseconds)
* `sid` - subaccount id that owns this transfer
* `tName` - token name
* `tAddr` - token contract address
* `typ` - transfer type, one of: `"DEPOSIT"`, `"WITHDRAW"`
* `st` - transfer status, one of: `"SUBMITTED"`, `"PENDING"`, `"COMPLETED"`, `"REJECTED"`
* `amt` - transfer amount
* `fee` - transaction fee
* `iniBk` - block number when the transfer was initiated (optional)
* `finBk` - block number when the transfer was finalized (optional)
* `iniTx` - Transaction hash of the initiation transaction (optional)
* `finTx` - Transaction hash of the finalization transaction (optional)
* `lzAddr` - LayerZero destination address for cross-chain bridge transfers (optional)
* `lzEid` - LayerZero endpoint id identifying the destination chain
#### Unsubscribing from Channels
To `unsubscribe` from a channel, send the same payload used to subscribe but with `unsubscribe` as the `event` type. Alternatively, disconnecting your entire connection will end all subscriptions. Note that reconnecting will consume rate limits. See [System Limits](/developer-guides/trading-api/system-limits) for more details.
```json
{
"event": "unsubscribe",
"data": {
"type": "MarketPrice",
"symbol": "" // e.g. "BTCUSD", "ETHUSD"
}
}
```
#### Ping / Pong
WebSocket connections include protocol-level ping/pong frames that are handled automatically and are not exposed at the application layer. However, some clients may require explicit liveness checks or latency measurement. In these scenarios, the gateway supports an application-level `ping` event:
```json
// Request message payload
{
"event": "ping"
}
// Response message
{
"e": "pong",
"t":
}
```
* `e` - `pong` response from a previous `ping`
* `t` - server timestamp this message was emitted at (epoch in milliseconds)
{% hint style="info" %}
This mechanism is optional and is not required to maintain the WebSocket connection. ***Note that is not yet available on mainnet.***
{% endhint %}
#### Exception Handling
Error responses are returned directly as a reply to the originating event (e.g. `subscribe`, `unsubscribe`). They follow a unified shape:
```json
{
"ok": false,
"code": "UNKNOWN_PRODUCT"
}
```
* `ok` indicates whether the request succeeded
* `code` a machine-readable error code present when `ok` is `false`
| Error codes | Description |
|---|
UNKNOWN_PRODUCT | The provided symbol does not match any known product. |
VALIDATION_ERROR | The request payload failed validation (e.g. missing or invalid fields). |
SUBSCRIPTION_FAILED | The server was unable to subscribe to the requested topic. |
UNSUBSCRIBE_FAILED | The server was unable to unsubscribe from the requested topic. |
RATE_LIMIT | Too many requests, the client has been rate-limited. |
INTERNAL_ERROR | An unexpected server-side error occurred. |
SUBSCRIPTION_LIMIT_EXCEEDED | Too many subaccount subscriptions on this connection. |
{% hint style="success" %}
A successful response would simply just return `{ "ok": true, ... }`
{% endhint %}
# WS2 Migration Guide
Ethereal highly encourages all developers to upgrade their trading bots from the Socket.io gateway to our new, highly optimised WebSocket gateway.
We built the architecture from the ground up to provide a strictly superior trading and market data experience. By moving to native WebSockets, your integration will immediately benefit from:
* **Low latency**: Direct, raw WebSocket connections strip away the heavy Socket.io protocol overhead.
* **Higher throughput**: Tighten update intervals when streaming feeds.
* **Smaller payloads**: Minified JSON keys reduce bandwidth usage and parsing times.
* **Richer data:** Additional fields in certain streams that did not exist previously, including timestamp in all feeds.
If you are upgrading an existing trading bot, you will need to transition your connection logic, subscription payloads, and response parsers.
{% hint style="warning" %}
Both gateways will run side-by-side during the migration period. The Socket.IO gateway is deprecated and will be removed in a future release. Migrate to the native WebSocket gateway as soon as possible.
{% endhint %}
### Key Differences
Below summarises the breaking changes between the legacy Socket.IO gateway and the new native WebSocket gateway.
*Connection*
* **URL:** `wss://ws.ethereal.trade/v1/stream` to `wss://ws2.ethereal.trade/v1/stream`
* **No Socket.IO library:** use native `WebSocket` (browser) (or e.g. `ws` Node.js)
* **Max connection lifetime:** reduced from 12 hours to \~4 hours. Server closes with code `1000`, reason `"please reconnect"`. You must implement your own reconnection logic.
*Streams*
* **Renamed streams:** `BookDepth` renamed to `L2Book`, and `MarketPrice` renamed to `Ticker`. `Ticker` includes additional fields not available in `MarketPrice`.
* **New stream:** `PositionUpdate` (subaccount-based, WS2-only)
* **Market stream key:** `productId` (UUID) replaced by `symbol` (e.g., `"ETH-USD"`) for better usability
*Protocol*
* **Message format:** `socket.emit('subscribe', payload)` to `ws.send(JSON.stringify({ event: 'subscribe', data: payload }))`
* **Single message handler:** per-stream event listeners replaced by a single `onmessage` handler
* **Error format:** `{ status: 'BadRequest', error: '...' }` on `exception` event to `{ ok: false, code: 'VALIDATION_ERROR' }` inline
### Dry Run Execution
The legacy Socket.IO gateway supported dry run execution as a streaming event, allowing clients to subscribe and receive simulated order execution results in real time. **WS2 does not offer a dry run stream**. To perform dry run executions, you must use the HTTP API instead. For example, where you previously subscribed to a dry run event via `socket.emit('dryRunOrder', payload)`, you should now make a REST call such as `POST /v1/order/dry-run` with the same order payload in the request body.
The response will contain the simulated execution result, including estimated fills, fees, and slippage as a single JSON response rather than a stream of updates. There is no WebSocket equivalent for this functionality in WS2, so any workflows that depended on streaming dry run updates will need to be adapted to use synchronous HTTP requests.
### AI Assisted Migration
The absolute fastest way to migrate your existing bot is to use an AI agent IDE (Cursor) or CLI tools like Claude Code.
{% hint style="info" %}
Copy the prompt below and paste it into your agent's chat. It contains all the necessary architectural context and schema changes required to refactor your code.
{% endhint %}
AI Migration Prompt (Click to expand)
```
I need to upgrade my Ethereal Trade trading bot's WebSocket architecture from the `Socket.io (v1)` gateway to the new `Native WebSockets (v2)` gateway for lower latency and higher throughput.
Please rewrite this code to use the standard native WebSocket client library.
CRITICAL MIGRATION RULES & SCHEMA CHANGES:
1. Connection URL:
- Old: `wss://ws.ethereal.trade/v1/stream` (socket.io)
- New: `wss://ws2.ethereal.trade/v1/stream` (mainnet) or `wss://ws2.etherealtest.net/v1/stream` (testnet)
- Adjust based on the environment in my code.
2. Connection Mechanics:
- Remove all `socket.io-client` dependencies. Use a standard WebSocket client (e.g., `ws` in Node.js).
- Implement automatic reconnection logic:
- Server closes connections after ~4 hours with code 1000 and reason "please reconnect".
- Idle connections with no message activity are closed after 2 minutes (server sends pings automatically, no client-side heartbeat needed).
- All subscriptions are lost on disconnect.
3. Subscription Payload Changes:
- `socket.io` `.emit()` is removed. All messages must be sent as `ws.send(JSON.stringify(payload))`.
- Subscriptions must be wrapped in an `event` envelope:
- Subscribe: `{ "event": "subscribe", "data": { "type": "", ... } }`
- Unsubscribe: `{ "event": "unsubscribe", "data": { "type": "", ... } }`
- Product channels now use `symbol` (e.g., "BTCUSD") instead of `productId` (UUID).
- Subaccount channels still use `subaccountId` (UUID) — no change needed for these.
Examples:
- Old: `socket.emit("subscribe", { "type": "BookDepth", "productId": "" })`
- New: `ws.send(JSON.stringify({ "event": "subscribe", "data": { "type": "L2Book", "symbol": "BTCUSD" } }))`
4. Channel Name Changes:
- `BookDepth` → `L2Book`
- `MarketPrice` → `Ticker`
- All other channels retain their names: `TradeFill`, `OrderUpdate`, `OrderFill`, `SubaccountLiquidation`, `TokenTransfer`.
5. Response Schema (Minified Keys):
- There is no longer event-based routing from socket.io. Use a single `ws.on('message', ...)` handler and `JSON.parse()` the payload.
- All data messages follow: `{ "e": "", "t": , "data": { ... } }`
- `e`: Event name (e.g., "L2Book", "Ticker"). Route logic based on this field.
- `t`: Server timestamp in milliseconds.
- `s` replaces `productId` inside data payloads (contains the symbol string).
- Subscribe/unsubscribe acknowledgments: `{ "ok": true }` on success, `{ "ok": false, "code": "" }` on failure.
- Reference the full response schemas: https://docs.ethereal.trade/developer-guides/trading-api/websockets.md
6. Error Handling:
- Errors are no longer emitted to a socket.io `exception` event.
- Normal errors return: `{ "ok": false, "code": "" }` (e.g., "UNKNOWN_PRODUCT", "VALIDATION_ERROR", "SUBSCRIPTION_LIMIT_EXCEEDED").
- Rate limit errors return `{ "ok": false, "code": "RATE_LIMIT" }` and the connection is immediately closed. Handle this in your reconnect logic.
```
# Code Snippets
Below are minimal examples demonstrating how to connect and subscribe to streams using socketio and native WebSockets. These snippets are intended as starting points for integration and are not production-ready.
## SocketIO Examples
Below is an example implemented using TypeScript and `socket.io-client`.
{% code expandable="true" %}
```typescript
import { io } from 'socket.io-client';
const API_BASE_URL = 'https://api.ethereal.trade';
const WS_BASE_URL = 'wss://ws.ethereal.trade/v1/stream';
const getProducts = async () => {
const res = await fetch(`${API_BASE_URL}/v1/product`);
const json = (await res.json()) as { data: { id: string }[] };
return json.data;
};
const main = async () => {
const ws = io(WS_BASE_URL, { transports: ['websocket'], autoConnect: false });
console.log(`Connecting to ws gateway ${WS_BASE_URL}`);
ws.on('connect', async () => {
console.log(`Connected to ${WS_BASE_URL}`);
const products = await getProducts();
products.forEach((product) => {
const bookDepthSubscriptionMessage = { type: 'BookDepth', productId: product.id };
ws.emit('subscribe', bookDepthSubscriptionMessage);
console.log(`Subscribed BookDepth:${product.id}`);
const marketPriceSubscriptionMessage = { type: 'MarketPrice', productId: product.id };
ws.emit('subscribe', marketPriceSubscriptionMessage);
console.log(`Subscribed MarketPrice:${product.id}`);
});
});
ws.on('connecting', () => console.log('Attempting connection...'));
ws.on('disconnect', () => console.log('Disconnected'));
ws.on('error', (err) => console.log('Error encountered', err));
ws.on('exception', (err) => console.log('Caught exception', err));
ws.on('reconnect_attempt', () => console.log('Attempting to reconnect...'));
// --- Subscription stream handlers --- //
ws.on('BookDepth', (message) => console.log('[BookDepth]', JSON.stringify(message)));
ws.on('MarketPrice', (message) => console.log('[MarketPrice]', JSON.stringify(message)));
// Explicitly connect to ws stream _after_ binding message callbacks.
ws.connect();
};
void main();
```
{% endcode %}
Another example using Java to listen on `BookDepth`.
{% code expandable="true" %}
```java
package com.example.ethereal;
import io.socket.client.IO;
import io.socket.client.Socket;
import io.socket.emitter.Emitter;
import java.net.URI;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
public class Example {
private Socket client;
private CountDownLatch connectionLatch = new CountDownLatch(1);
public static void main(String[] args) {
EtherealClient client = new EtherealClient();
try {
client.connect();
client.subscribeToBookDepth("6dae67f4-c502-4cc1-8d1a-38ab021b2c76");
// Keep running for 30 seconds
Thread.sleep(30000);
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
e.printStackTrace();
} finally {
client.disconnect();
}
}
public void connect() throws InterruptedException {
System.out.println("Connecting to Ethereal Testnet WebSocket...");
URI serverUri = URI.create("wss://ws.etherealtest.net/v1/stream");
IO.Options options = new IO.Options();
options.transports = new String[]{"websocket"};
options.upgrade = false;
options.timeout = 10000;
client = IO.socket(serverUri, options);
client.on(Socket.EVENT_CONNECT, new Emitter.Listener() {
@Override
public void call(Object... args) {
System.out.println("Connected! Socket ID: " + client.id());
connectionLatch.countDown();
}
});
client.on(Socket.EVENT_CONNECT_ERROR, new Emitter.Listener() {
@Override
public void call(Object... args) {
System.err.println("Connection failed: " + Arrays.toString(args));
connectionLatch.countDown();
}
});
client.on("BookDepth", new Emitter.Listener() {
@Override
public void call(Object... args) {
System.out.println("BookDepth: " + Arrays.toString(args));
}
});
client.on("exception", new Emitter.Listener() {
@Override
public void call(Object... args) {
System.err.println("Server exception: " + Arrays.toString(args));
}
});
client.connect();
if (!connectionLatch.await(15, TimeUnit.SECONDS)) {
throw new RuntimeException("Connection timeout");
}
}
public void subscribeToBookDepth(String productId) {
if (!client.connected()) {
System.err.println("Not connected!");
return;
}
Map request = new HashMap<>();
request.put("type", "BookDepth");
request.put("productId", productId);
System.out.println("Subscribing: " + request);
client.emit("subscribe", request);
}
public void disconnect() {
if (client != null) {
System.out.println("Disconnecting...");
client.disconnect();
client.close();
}
}
}
```
{% endcode %}
{% hint style="info" %}
For Python developers, our Python SDK offers a streamlined approach to WebSocket subscriptions Refer to the [Python SDK](/developer-guides/sdk/python-sdk) documentation for more information.
{% endhint %}
## Websocket Examples
Below is an example using the `ws` Typescript library.
{% code expandable="true" %}
```typescript
import WebSocket from 'ws';
import axios from 'axios';
axios.defaults.baseURL = 'https://api.ethereal.trade/v1';
const getProducts = async () => {
const res = await axios.get('/product');
return res.data.data;
};
const main = async () => {
const url = 'wss://ws2.ethereal.trade/v1/stream';
const ws = new WebSocket(url);
console.log(`Connecting to ws gateway ${url}`);
ws.on('open', async () => {
console.log(`Connected to ${url}`);
const products = await getProducts();
products.forEach((product: { id: string; ticker: string }) => {
const l2BookSubscriptionMessage = {
event: 'subscribe',
data: { type: 'L2Book', symbol: product.ticker },
};
ws.send(JSON.stringify(l2BookSubscriptionMessage));
console.log(`Subscribed L2Book:${product.ticker}`);
const tickerSubscriptionMessage = {
event: 'subscribe',
data: { type: 'Ticker', symbol: product.ticker },
};
ws.send(JSON.stringify(marketPriceSubscriptionMessage));
console.log(`Subscribed Ticker:${product.ticker}`);
});
});
ws.on('close', () => console.log('Disconnected'));
ws.on('error', (err) => console.log('Error encountered', err));
// --- Subscription stream handlers --- //
ws.on('message', (data) => {
const message = JSON.parse(data.toString());
switch (message.e) {
case 'L2Book':
console.log(`[L2Book] Received ${data.toString()}`);
break;
case 'Ticker':
console.log(`[Ticker] Received ${data.toString()}`);
break;
}
});
};
void main();
```
{% endcode %}
Another example using Rust with `tungstenite` to listen on a few feeds.
{% code expandable="true" %}
```rust
use futures_util::{SinkExt, StreamExt};
use serde::{Deserialize, Serialize};
use tokio_tungstenite::{connect_async, tungstenite::Message};
const BASE_URL: &str = "https://api.ethereal.trade/v1";
const WS_URL: &str = "wss://ws2.ethereal.trade/v1/stream";
#[derive(Debug, Deserialize)]
struct ProductPage {
data: Vec,
}
#[derive(Debug, Deserialize)]
struct Product {
ticker: String,
}
#[derive(Serialize)]
struct WsMessage {
event: &'static str,
data: SubscriptionData,
}
#[derive(Serialize)]
struct SubscriptionData {
r#type: &'static str,
symbol: String,
}
async fn get_products() -> Vec {
let url = format!("{}/product", BASE_URL);
reqwest::get(&url)
.await
.unwrap()
.json::()
.await
.unwrap()
.data
}
fn subscribe_msg(kind: &'static str, symbol: String) -> Message {
let msg = WsMessage {
event: "subscribe",
data: SubscriptionData {
r#type: kind,
symbol,
},
};
Message::Text(serde_json::to_string(&msg).unwrap().into())
}
#[tokio::main]
async fn main() {
let products = get_products().await;
let (ws_stream, _) = connect_async(WS_URL).await.unwrap();
let (mut write, mut read) = ws_stream.split();
for p in &products {
for kind in ["L2Book", "Ticker"] {
write
.send(subscribe_msg(kind, p.ticker.clone()))
.await
.unwrap();
println!("Subscribed {kind}:{}", p.ticker);
}
}
while let Some(Ok(msg)) = read.next().await {
match msg {
Message::Text(text) => println!("{text}"),
Message::Ping(data) => {
let _ = write.send(Message::Pong(data)).await;
}
Message::Close(_) => break,
_ => {}
}
}
}
```
{% endcode %}
# Socket.io (deprecated)
Ethereal uses [Socket.io](https://socket.io/docs/v4/), a library that extends the standard WebSocket protocol. Socket.io provides ready-made client libraries in multiple languages with automatic reconnection handling and built-in ping/pong frames to maintain stable connections, saving developers from implementing these basic features themselves.
Refer to [Socket.io](https://socket.io/docs/v4/#client-implementations) for language specific client implementations.
{% hint style="warning" %}
Socket.io **has now been replaced with native web sockets and will be removed in a future release**. Ensure you transition to using native websockets to prevent any disruptions in the future.
{% endhint %}
{% hint style="success" %}
**Migration** *Native* WebSockets will be available on testnet first for integrators to test and provide feedback. After mainnet release, both Socket.io and native WebSockets will remain available for a transition period to allow a smooth migration without disruption.
{% endhint %}
| URL | Status |
|---|
wss://ws.ethereal.trade/v1/stream | Live - Soon to be deprecated |
### WebSockets
Ethereal also offers WebSocket support, which communicates with plain JSON payloads, resulting in lower latency, reduced overhead, and smaller message sizes. This makes it well-suited for latency-sensitive integrations and lightweight clients that don't need the built-in reconnections provided by Socket.io.
Websockets support a subset of the Socket.io feeds. If you require additional data streams, use the Socket.io gateway above which supports the full set of subscription types.
## `Socket.io` Subscription Streams
### Subscribe
The WebSocket gateway offers the following subscription streams:
**`BOOK_DEPTH`** - Provides order book depth updates for a specific product.
{% code expandable="true" %}
```json
// Subscription message payload
{
"type": "BookDepth",
"productId": ""
}
// Response message
{
"timestamp": "",
"previousTimestamp": "",
"productId": "",
"asks": [[price: string, quantity: string]],
"bids": [[price: string, quantity: string]],
"t": ""
}
```
{% endcode %}
* `BookDepth` events are emitted on a configurable fixed interval (as of writing, this is configured to be **once every 200ms**)
* `previousTimestamp` is in milliseconds and represents the last time the `BookDepth` emitted
* `timestamp` also in milliseconds and the system timestamp of when this `BookDepth`was emitted
* Using both the `previousTimestamp` and `timestamp` you can infer whether or not any events were missed during connection or during consumption
* `asks` an array of price/quantity tuples representing asks
* `bids` an array of price/quantity tuples representing bids
* `t` represents server time when response was published (epoch in miliseconds)
{% hint style="warning" %}
A `BookDepth` message of the current book **(up to 100 price levels per side)** is emitted back on initial connection. Every subsequent message is a price level diff with absolute quantities. A zero quantity price diff indicates that this level has been removed.
{% endhint %}
**`MARKET_PRICE`** - Delivers real-time market price updates for a specified product.
{% code expandable="true" %}
```json
// Subscription message payload
{
"type": "MarketPrice",
"productId": ""
}
// Response message (same as `/v1/product/market-price`)
// @see: https://api.ethereal.trade/docs#/Product/ProductController_getMarketPrice
{
"productId": "",
"bestBidPrice": numberString,
"bestAskPrice": numberString,
"oraclePrice": numberString,
"price24hAgo": numberString,
"t": ""
}
```
{% endcode %}
* `MarketPrice` events are emitted on a configurable fixed interval (currently configured to be **once every second**)
* `t` represents server time when response was published (epoch in miliseconds)
**`ORDER_FILL`** - Notifies when orders are filled for a specific subaccount.
{% code expandable="true" %}
```json
// Subscription message payload
{
"type": "OrderFill",
"subaccountId": ""
}
// Response message (same as `/v1/order/fill`)
// @see: https://api.ethereal.trade/docs#/Order/OrderController_listFillsBySubaccountId
{
"data": [
{
"id": "",
"orderId": "",
"clientOrderId": "string",
"price": numberString,
"filled": numberString,
"type": "LIMIT|MARKET",
"side": 0|1,
"reduceOnly": boolean,
"feeUsd": numberString,
"isMaker": boolean,
"productId": "",
"subaccountId": "",
"createdAt": ""
}
],
"t": ""
}
```
{% endcode %}
* `OrderFill` events are emitted in real-time as they occur
* `t` represents server time when response was published (epoch in miliseconds)
**`TRADE_FILL`** - Provides a stream of trades that have occurred filtered by product.
{% code expandable="true" %}
```json
// Subscription message payload
{
"type": "TradeFill",
"productId": ""
}
// Response message
{
"data": [
{
"id": "",
"price": numberString,
"filled": numberString,
"takerSide": 0|1,
"createdAt": ""
}
],
"productId": "",
"t": ""
}
```
{% endcode %}
* `TradeFill` events are emitted in real-time as they occur
* `t` represents server time when response was published (epoch in miliseconds)
* Similar to `OrderFill`, an array of trade fills will be emitted in a single message, grouped by the product they were traded on
**`ORDER_UPDATE`** - Provides updates about order status changes for a specific subaccount.
{% code expandable="true" %}
```json
// Subscription message payload
{
"type": "OrderUpdate",
"subaccountId": ""
}
// Response message (same as `/v1/order`)
// @see https://api.ethereal.trade/docs#/Order/OrderController_listBySubaccountId
{
"data": [
{
"id": "",
"clientOrderId": "string",
"type": "LIMIT"|"MARKET",
"availableQuantity": numberString,
"quantity": numberString,
"side": 0|1,
"productId": "",
"subaccountId": "",
"status": "",
"reduceOnly": boolean,
"close": booleanue,
"updatedAt": "",
"createdAt": "",
"sender": "",
"price": numberString,
"filled": numberString,
"stopPrice": numberString,
"stopType": "",
"stopPriceType": "",
"timeInForce": "",
"expiresAt": "",
"postOnly": boolean,
"groupContingencyType": "",
"groupId": ""
}
],
"t": ""
}
```
{% endcode %}
* `OrderUpdate` events are emitted in real-time
* `t` represents server time when response was published (epoch in miliseconds)
{% hint style="warning" %}
Only the latest update processed is emitted and intermediary states are omitted.
{% endhint %}
**`SUBACCOUNT_LIQUIDATION`** - Provides an update when a subaccount is liquidated.
{% code expandable="true" %}
```json
// Subscription message payload
{
"type": "SubaccountLiquidation",
"subaccountId": ""
}
// Response message
{
"subaccountId": "",
"liquidatedAt": "",
"t": ""
}
```
{% endcode %}
* `SubaccountLiquidation` events are emitted in real-time
* `subaccountId` the subaccount that has been liquidated, `liquidatedAt` the time (in ms, since the Unix epoch) when the liquidation occurred
* `t` represents server time when response was published (epoch in miliseconds)
**`TOKEN_TRANSFER`** - Updates on token transfers (deposits/withdrawals) for a specific subaccount.
{% code expandable="true" %}
```json
// Subscription message payload
{
"type": "TokenTransfer",
"subaccountId": ""
}
// Response message (same as `/v1/token/transfer` with pagination)
// @see https://api.ethereal.trade/docs#/Token/TokenController_listTransfers
{
"id": "",
"initiatedBlockNumber": numberString,
"finalizedBlockNumber": numberString,
"status": "",
"subaccountId": "",
"tokenName": "string",
"tokenAddress": "",
"type": "WITHDRAW"|"DEPOSIT",
"amount": numberString,
"lzDestinationAddress": "",
"lzDestinationEid": number,
"fee": numberString,
"createdAt": "",
"initiatedTransactionHash": "",
"finalizedTransactionHash": "",
"t": ""
}
```
{% endcode %}
* `t` represents server time when response was published (epoch in miliseconds)
{% hint style="success" %}
*Each subscription requires specific parameters as shown in the formats above. To subscribe to these streams, emit a 'subscribe' event to the socket with the appropriate subscription message.*
{% endhint %}
{% hint style="warning" %}
During connection establishment ensure `websocket` is the only configured transport (i.e. `transports: ['websocket']`).
{% endhint %}
### Unsubscribe
To stop receiving data from a previously established subscription, you can unsubscribe using the same payload format as your original subscription. Simply emit an `unsubscribe` event to the socket with the identical payload structure you used when subscribing.
### Handling `Socket.io` Exceptions
Exceptions are exposed in its own event aptly named "*exception*". Exceptions follow the following shape:
```typescript
{
pattern: 'order:dryRun',
status: 'BadRequest',
error: {
message: [
'subaccount is not a valid subaccount',
]
}
}
```
* `pattern` indicates the source event pattern if available e.g. "subscribe"
* `status` the error status
* `error` general body of the error its shape changes depending on the status
# TradingView API
Ethereal exposes a [TradingView UDF-compatible](https://www.tradingview.com/charting-library-docs/latest/connecting_data/UDF/) API for querying historical OHLCV candlestick data, resolving symbol information, and searching available markets. This API powers charting integrations and can be used by any client that supports the TradingView UDF protocol.
| Environment | URL |
|---|
| Mainnet | https://tradingview.ethereal.trade |
| Testnet | https://tradingview.etherealtest.net |
The full API specification (including request/response schemas, parameter validation rules, and error codes) is available via Swagger UI and as a downloadable OpenAPI spec. Use it to explore the API interactively or generate client SDKs:
| Resource | URL |
|---|
| Swagger UI | https://tradingview.ethereal.trade/docs |
| OpenAPI spec | https://tradingview.ethereal.trade/openapi.json |
### API Endpoints & Example
Each price type exposes the following endpoints:
| Endpoint | Description |
|---|
GET /{price-type}/config | UDF data feed configuration (called on init) |
GET /{price-type}/symbols | Resolve full symbol metadata for a given ticker |
GET /{price-type}/search | Search for symbols with fuzzy matching |
GET /{price-type}/history | Historical OHLCV bar data for a symbol/resolution |
GET /{price-type}/time | Current server time (Unix seconds) |
*Where `{price-type}` is either last-price or oracle-price.*
### API Price Types
Every endpoint exists under two parallel route prefixes, each querying a different data source:
| URL Prefix | Description |
|---|
/v1/last-price | Last Price - derived from actual executed trades on the exchange. Only taker fills are included (self-trades, if any, are excluded). |
/v1/oracle-price | Oracle Price - derived from oracle price feed snapshots. Represents the reference price used for mark pricing, funding, and liquidations. |
* **Last price** reflects where trades actually executed on the exchange. It is built from taker order fills (excluding self-trades) and includes meaningful volume data. During low-activity periods there may be gaps where no. trades occurred.
* **Oracle price** reflects the external reference price used for mark pricing, funding, and liquidations. It is updated continuously by the oracle, producing a smoother and more complete price line — but volume data reflects oracle update frequency, not trade activity.
{% hint style="info" %}
In most charting scenarios, oracle price provides a more continuous price line, while last price shows where actual trades occurred and includes meaningful volume data.
{% endhint %}
### Ticker Format & Resolution
Symbols follow the format `{TICKER}-{Type}`, e.g. `ETHUSD-Perp` or `BTCUSD-Perp`. *Currently only `Perp` (perpetual) is supported, with `Spot` coming soon.*
**Examples:** `ETHUSD-Perp`, `BTCUSD-Perp`, `SOLUSD-Spot`
Supported candlestick resolutions:
* **Minutes:** `1`, `3`, `5`, `15`, `30`
* **Hours:** `60` (1h), `120` (2h), `240` (4h), `480` (8h), `720` (12h)
* **Days and above:** `1D`, `3D`, `1W`, `1M`
{% hint style="info" %}
Ethereal currently only supports `Perp` type with `Spot` later.
{% endhint %}
#### Example oracle-price Candles
Fetch 1-hour oracle price candles for ETHUSD-Perp:
{% code overflow="wrap" %}
```bash
GET https://tradingview.ethereal.trade/v1/oracle-price/history?symbol=ETHUSD-Perp&resolution=60&from=1704067200&to=1704110400&countback=100
```
{% endcode %}
The history endpoint returns OHLCV arrays:
```json
{
"s": "ok",
"t": [1704067200, 1704070800, 1704074400],
"o": [42000.50, 42100.00, 42050.75],
"h": [42150.00, 42200.00, 42100.00],
"l": [41950.00, 42050.00, 41980.00],
"c": [42100.00, 42050.75, 42080.25],
"v": [125.5, 98.3, 110.7]
}
```
| Field | Description |
|---|
s | Status: ok, no_data, or error |
t | Timestamps (Unix seconds) |
o | Open prices |
h | High prices |
l | Low prices |
c | Close prices |
v | Volumes |
{% hint style="info" %}
Bars are returned in ascending chronological order (oldest first). When no data exists for the requested range, the response is `{ "s": "no_data" }`.
{% endhint %}
### Limitations & Intended Use
Limitations:
* **No authentication:** this is a public, read-only API
* **No streaming / WebSocket support:** the API is polling-based. Use the `history` endpoint to fetch updated bars
* **No marks or timescale marks:** `supports_marks` and `supports_timescale_marks` are `false`.
* **No group requests:** symbols must be resolved individually.
* **Query range limits:** each resolution has a maximum time range per request. For example, 1-minute bars are limited to a 1-hour window, while monthly bars can span up to 10 years. If you need more data, paginate by shifting the `from`/`to` window.
* **Last price gaps:** the last price feed reflects actual trade executions. During low-liquidity periods, there may be gaps in the data where no trades occurred.
* **Volume on oracle price:** volume data on oracle price candles reflects oracle update frequency, not trade volume. Use last price candles for meaningful volume data.
* **Rate limiting:** TradingView API follows the same rate limits defined at [System Limits](/developer-guides/trading-api/system-limits).
This API is designed for:
* **TradingView charting integrations:** connect directly as a UDF data feed in the [TradingView Charting Library](https://www.tradingview.com/charting-library-docs/)
* **Historical data analysis:** fetch OHLCV candle data for backtesting or analytics
* **Building custom charts:** use the raw OHLCV arrays to render charts in any frontend
It is **not** intended for:
* Real-time trade execution or order placement
* Tick-level or sub-minute trade data
* Account-specific or authenticated data retrieval
# Onchain Settlement
{% hint style="warning" %}
*Documentation for this page is still in progress*.
{% endhint %}
# SDK
Ethereal provides SDKs that wrap both the Trading API and the WebSocket gateway. These SDKs are designed for integration, automation, and strategy development, with a focus on utility and correctness rather than hyper-optimized submit-and-cancel flows. They also serve as a useful reference implementation if you ever need to debug discrepancies between your own client code and the expected API behavior.
As of writing, there is one officially supported SDK for Python. Full documentation is available [here](/developer-guides/sdk/python-sdk).
Members of the Ethereal community also build and maintain SDKs in other languages. **These are third-party projects, not developed or maintained by the Ethereal team**. They are listed here for convenience, but you should review their code and evaluate their suitability for your use case independently.
* **Rust SDK:**
* **Go SDK:**
{% hint style="info" %}
If you have any questions please join the Discord ask in **#developer-support**.
{% endhint %}
# Python SDK
For developers seeking a streamlined integration experience, Ethereal Exchange offers an officially supported Python SDK that provides comprehensive access to the trading API and websocket gateway. The SDK abstracts away many of the implementation complexities, handling authentication, request formatting, and signature generation while offering intuitive interfaces for market data retrieval, order management, and account operations.
For complete documentation, code examples, and implementation guides, please refer to our comprehensive SDK documentation available [here](https://meridianxyz.github.io/ethereal-py-sdk/).
{% hint style="info" %}
At the time of writing, Ethereal only has support for a Python SDK with many more languages coming soon.
{% endhint %}
# Support
Read this entire section before opening a ticket. Tickets in discord will take time to review.
* [Deposits to Ethereal](/protocol-reference/support/deposits-to-ethereal)
* [Withdrawals from Ethereal](/protocol-reference/support/withdrawals-from-ethereal)
* [Trading Support](/protocol-reference/support/trading-support)
* [Connectivity & Linked Signers](/protocol-reference/support/connectivity-and-linked-signers)
* [I've been scammed](/protocol-reference/support/ive-been-scammed)
# Deposits to Ethereal
[https://app.ethereal.trade/](https://deposit.ethereal.trade/)
Deposits from multiple chains directly to Ethereal. Fastest option for most users. Swaps all assets to USDe before fast depositing to your account.
**Process:**
1. Connect wallet at
2. Select source your wallet, transfer crypto, or use traditional finance
3. Enter amount ($10 minimum)
4. Confirm transaction in wallet
5. Wait for bridge confirmation (typically under 5 minutes)
If you have any issues, join the Ethereal Discord and open a bridge ticket or head to
# Withdrawals from Ethereal
Outbound transfers use LayerZero for cross-chain delivery.
1. Go to Portfolio in [app.ethereal.trade](https://app.ethereal.trade)
2. Select Withdraw
3. Choose destination chain
4. Enter amount (must be ≤ Available Margin)
5. Confirm transaction
**Processing time:** Varies by destination chain. Check here and your withdrawals tab in the Ethereal app for further questions
# Trading Support
### Common Issues
#### "Why was I liquidated?"
Oracle price hit your liquidation price. Check Trade History for details.
Uses **oracle price**, not last trade price. In cross margin all positions share margin - a loss in one increases the risk for all other positions.
Liquidations on Ethereal are triggered when your account exceeds maintenance margin. See [Liquidations](/trading/perpetual-futures/liquidations)
#### "My TP triggered but I lost money"
TP/SL triggers on oracle price, executes at market price.
Your TP triggered when oracle hit your target, but the fill happened at a worse price due to slippage. More common with large positions, thin liquidity, or volatile periods. Ethereal is not able to gurantee execution pricing, especially during periods of volatility.
Default slippage for TP/SL positions is 5%
#### "I can't open a position / insufficient margin"
Available Margin ≠ Total Balance.
**Available = Total − Position Margin − Order Reserves − Unrealized Losses**
Close positions to increase available margin. Unrealized losses and unrealized gains are not used in withdrawable margin as a security precaution.
#### "My limit order won't fill"
Limit orders only fill at your price or better. Market moved away from your price. Order stays open until price returns, you cancel, or it expires.
#### "I used a limit order, but I was still charged a fee"
If your limit order uses liquidity available in the orderbook, then it is a taker order.
Use "post only" if you want to gurantee your order is not matched with a maker in the book.
***
### Liquidation
#### How It Works
Liquidation triggers when account equity falls below maintenance margin.
* Uses oracle **price**, not last trade price
* Liquidation price shown when you open a position
* Note: If you have multiple positions open, all positions (EX: BTC and ETH long) share the same margin, and can increase/decrease your liquidation price.
* Once triggered, positions are transferred to the liquidator, see [Liquidations](/trading/perpetual-futures/liquidations) for more info
* Details visible in Trade History
#### Cross Margin
All positions share one margin pool. If you have 3 positions, BTC, ETH and SOL, all long, they share the same margin pool - if all go down, it decreases the amount of margin available for all other positions, and increases your liquidation price.
***
### Order Execution
#### Limit Orders
Fill at your price or better, or not at all.
No partial fills unless order was partially matched before price moved.
#### Market Orders
Execute immediately at best available price.
#### TP/SL Orders
**Trigger on oracle price. Execute as market order.**
Gap between trigger and fill is normal.
**Example: TP triggered at $100, position closed at $98**
| What Happened | Why |
| ----------------------------- | ------------------------- |
| TP triggered | Mark price hit $100 |
| Fill at $98 | Market price at execution |
| Result: less profit (or loss) | Slippage |
**More slippage with:**
* Large positions
* Low liquidity markets
* High volatility
* Tight profit targets
**Slippage tolerance:** Market TP/SL has default tolerance. If market moves beyond this, order may not fill.
For full order mechanics: [Ethereal Docs - Order Types](https://docs.ethereal.trade/)
***
### Margin
#### Available Margin
**Available = Total Balance − Position Margin − Order Reserves − Unrealized Losses**
| Component | What It Is |
| ----------------- | ---------------------------------- |
| Total Balance | Everything in your account |
| Position Margin | Locked in open positions |
| Order Reserves | Reserved for unfilled limit orders |
| Unrealized Losses | Current losses on open positions |
#### Freeing Up Margin
* Close or reduce positions
* Cancel open limit orders
* Unrealized losses reduce available until you close
See [Margining](/trading/perpetual-futures/margining)for more info
***
### Still Need Help?
Open a ticket in [Discord](https://discord.gg/etherealdex) #support with:
* Wallet address
* Transaction hash (if applicable)
* Screenshot of error
* What you were trying to do
# Connectivity & Linked Signers
Recommended Wallets for best experience:
* Rabby Wallet
* Frame Wallet
These work reliably with Ethereal. If you're having issues with another wallet, switching to Rabby usually fixes it.
#### Known Problem Wallets
| Wallet | Issue |
| ---------------------------- | --------------------------------------- |
| Coinbase Wallet | Connection issues, especially on mobile |
| Coinbase Wallet with Passkey | Frequent signing failures |
| MetaMask Mobile | Inconsistent connection |
| Binance/OKX/Exchange Wallet | Do not support custom chains |
If you're using one of these and having problems, try Rabby or Frame instead.
#### Quick Fixes
**Can't connect at all:**
1. Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
2. Clear browser cache
3. Try a different browser
4. Switch to Rabby
**Stuck in connection loop:**
1. Disconnect Ethereal from your wallet's connected sites
2. Clear browser cache
3. Reconnect
**Wrong network error:** Approve the network switch when prompted. If stuck, manually switch networks in your wallet and refresh.
***
### One-Click Signing Issues
If one-click trading stops working or behaves unexpectedly:
1. Go to Settings
2. Turn off one-click signing
3. Turn it back on
4. Sign the message when prompted
This resets the session and fixes most issues.
***
### Linked Signer Issues
If you're having problems with linked signers (orders failing, signer not recognized, quota errors):
1. Go to the Linked Signers page in Settings
2. Remove one of the signers
3. Link a new one
#### Linked Signers Can't Withdraw
This is intentional. Linked signers only handle orders. Withdrawals always require your main wallet signature.
# I've been scammed
Ethereal is non custodial and is not able to move assets, points, or make any other transcations on your behalf.
We recommend using an entirely new wallet address on a safe machine.
To recover any assets, we recommend groups like [Seal 911](https://www.securityalliance.org/seal-911)
# API Hosts
## Mainnet
| Service | Endpoint |
| ----------------------------------- | --------------------------------------------------------- |
| HTTP API | |
| HTTP API Specification | |
| HTTP API Reference | |
| Archive API | |
| Archive API Specification | |
| Archive API Reference | |
| Websocket API Gateway | wss\://ws.ethereal.trade |
| Exchange UI Application | [https://app.ethereal.trade](https://app.ethereal.trade/) |
| TradingView API (Last traded price) | |
| TradingView API (Oracle price) | |
## Testnet
| Service | Endpoint |
| ----------------------------------- | ------------------------------------------------------ |
| HTTP API | |
| HTTP API Specification | |
| HTTP API Reference | |
| Archive API | |
| Archive API Specification | |
| Archive API Reference | |
| Websocket API Gateway | wss\://ws.etherealtest.net |
| Exchange UI Application | |
| TradingView API (Last traded price) | |
| TradingView API (Oracle price) | |
# Contracts
## Mainnet
| Service | Endpoint |
| -------------- | ---------------------------------- |
| HTTP RPC | |
| WS RPC | wss\://ws.ethereal.trade |
| Block Explorer | |
| Chain ID | 5064014 |
| Gas Token | USDe (18 decimals) |
Contracts: `0xB3cDC82035C495c484C9fF11eD5f3Ff6d342e3cc`
### Address & ABI
To get the latest version of the proxy address, query for the `verifyingContract` address:
```bash
curl -X 'GET' \C
'https://api.ethereal.trade/v1/rpc/config' \
-H 'accept: application/json'
```
Navigate to the block explorer and use the `domain.verifyingContract` address to retrieve the ABI. All Ethereal smart contracts include verified source code and ABI data post-deployment. SDKs also have ABIs.
## Testnet
| Service | Endpoint |
| -------------- | ----------------------------------- |
| HTTP RPC | |
| WS RPC | wss\://rpc.etherealtest.net |
| Block Explorer | |
| Chain ID | 13374202 |
| Gas Token | USDe (18 decimals) |
# Audits
Exchange Audits:
* [Guardian Audits - Exchange](https://drive.google.com/file/d/1HeJGheenSIK2AcA113GV-ErQNFELDAGD/view?usp=sharing)
* [Chain Security - Exchange](https://drive.google.com/file/d/1bgSfCaiyfC438nUNB3K8UVe5Eg006yKb/view?usp=sharing)
Season Zero Audit:
* [Guardian Audits - Season Zero](https://drive.google.com/file/d/1HMihTcqKwt75pTAct9F0H3noqDtCJ3u3/view)
# Media Kit
## Ethereal Logos
## Ethereal Colours
## Brand Guidelines
# Meridian Media Kit (WIP)
## Meridian Logos