# Welcome

Aleno provides high-performance, cross-chain price and liquidity data for digital assets, purpose-built for oracle networks, DeFi analytics, and institutional-grade monitoring. Our infrastructure aggregates both **on-chain DEX** and **centralized exchange (CEX)** market data with a strong emphasis on transparency, composability, and real-time responsiveness.

***

### **What You Can Do With This API**

* 🔍 **Get real-time prices** from CEXs and DEXs across multiple chains
* 💧 **Access deep liquidity metrics**, including USD TVL and 24h volume
* 🧮 **Discover token pairs and pools** using normalized identifiers
* ⚡ **Power oracles, dashboards, and risk systems** with production-ready endpoints
* 🧠 **Integrate pricing logic** based on our liquidity- and volume-weighted methodology

***

### **Core Concepts**

* **Assets** — Tokens normalized across chains with canonical symbols (e.g., `SOL`, `WBTC`, `USDC`).
* **Pools** — Liquidity pools aggregated across protocols and chains.
* **Tickers** — Aggregated prices for asset pairs (e.g., `WBTC/USD`), combining DEX + CEX sources.
* **DEX Protocols** — Coverage includes Uniswap v2/v3, Curve, Balancer, Trader Joe v2.x, Solidly, Orca, and more.
* **Chains** — Data spans EVM chains (Ethereum, Arbitrum, Optimism, etc.) and non-EVM chains (Solana), with more being added.

***

### **Quickstart**

1. **Get an API key** — Required for all routes.
2. **Try the `/v1/assets/ticker` endpoint**

   ```bash
   curl -X GET "https://pricing.aleno.ai/v1/assets/ticker?symbol=WBTC/USD" -H "x-api-key: YOUR_API_KEY"
   ```
3. **Explore endpoints** via the navigation pane.

***

### **Support and Integrations**

* 💬 Have questions? Get in touch with our team.
* 📈 Need custom metrics, alerts, or higher throughput? Reach out for enterprise options.
* 🧩 Looking to integrate with Chainlink, Pyth, or custom oracles? We're built for it.


# Supported Liquidity Sources

### **Blockchains (DEX Sources)**

Aleno currently indexes pools across the following EVM and non-EVM blockchains. Additional chains are in the pipeline.

**✅ Currently Supported**

| Chain     | Chain ID (Aleno) |
| --------- | ---------------- |
| Ethereum  | `eth`            |
| Solana    | `solana`         |
| Avalanche | `avalanche`      |
| BNB Chain | `bsc`            |
| Optimism  | `optimism`       |
| Base      | `base`           |
| Arbitrum  | `arbitrum`       |
| Polygon   | `polygon`        |
| Sui       | `sui`            |
| Sonic     | `sonic`          |
| Hedera    | `hedera`         |

***

### **Supported DEX Protocols**

**✅ Supported AMM Architectures**

| Category               | Protocols / Variants                                           |
| ---------------------- | -------------------------------------------------------------- |
| **Uniswap v2-style**   | Uniswap v2, Sushiswap, PancakeSwap, and other forks            |
| **Uniswap v3-style**   | Uniswap v3, Algebra-based AMMs                                 |
| **Balancer-style**     | Balancer                                                       |
| **Curve-style**        | Curve                                                          |
| **Solidly-style**      | Solidly, Solidly v3                                            |
| **Solana-native DEXs** | Orca, Raydium, Meteora                                         |
| **Bin-based AMMs**     | Trader Joe v2.1, Trader Joe v2.2 (Liquidity Book architecture) |
| **Uniswap v4-style**   | Uniswap v4                                                     |

***

### **Centralized Exchanges (CEXs)**

Aleno aggregates order book and market price data from the following centralized exchanges:

**✅ Currently Supported**

* **Binance**
* **Bitget**
* **Bybit**
* **KuCoin**
* **MEXC**

***

### **RWA**

We partner with a TradFi company that aggregates prices from multiple sources to ensure high quality and availability. These sources include Primary markets including Nasdaq.

Data includes Equities, Commodities, FX, Economic Indicators among others...

Please reach us out to know more about data availability, granularity and refresh-rate.

***

### **🚧** Additionnal Assets to be added (on demand)

Here is a list of chains, protocols, and CEXs that can be added quickly. If anything is missing, feel free to reach out to us.

#### Blockchains

| Chain     | Chain ID (Aleno) |
| --------- | ---------------- |
| Berachain | `bera`           |
| Botanix   | `botanix`        |
| HyperEVM  | `hype`           |
| Mantle    | `mantle`         |
| Plasma    | `plasma`         |
| Katana    | `katana`         |
| Celo      | `celo`           |
| BOB       | `bob`            |
| XLayer    | `xlayer`         |
| MegaETH   | `megaeth`        |
| Monad     | `monad`          |

#### **Protocols**

If any protocols are missing from the already supported AMM structures, let us know and we will add them quickly.

| Category          | Protcols / Variants  |
| ----------------- | -------------------- |
| Maverick v2-style | Maverick (any chain) |
| Fluid-style       | Fluid (any chain)    |

#### **Centralized Exchanges (CEXs)**

Support for additional major CEXs is in progress, including OKX, Coinbase, and Gate.io.


# Asset Pricing Methodology

### **Overview**

Aleno computes real-time asset prices by aggregating data from both decentralized exchanges (DEXs) and centralized exchanges (CEXs). The methodology prioritizes data reliability, liquidity depth, and market representativeness.

***

### **DEX Pricing**

**1. Pool Discovery**

* For each asset, Aleno fetches all available DEX pools across supported chains and retain only the ones with enough liquidity and volume.
* Only pools that pass initialization checks (via on-chain RPC queries) and protocol whitelisting are retained.

**2. Quote Asset Selection**

* Among all valid pools for the asset, Aleno identifies the pool(s) where the counterparty token (quote asset) has:
  * The **highest USD liquidity** (`usdTvl`)
  * Reliable price reference (e.g., stablecoins like USDC/USDT or blue chips like WETH/ETH).
* Pools with illiquid or volatile quotes are excluded.

**3. Liquidity-Weighted Pricing**

* For all selected pools (possibly across multiple chains), Aleno computes the price of the asset relative to the quote using pool reserves and volumes.
* Each price is **weighted by a combination of:**
  * Pool USD liquidity (`usdTvl`)
  * 24h USD trading volume (`h24UsdVolume`)
* The final DEX price is a **liquidity + volume weighted average** across all qualifying pools.

**4. Quote Normalization via Kraken**

* To convert token pairs into a consistent USD-denominated price (e.g., USDC → USD), Aleno uses Kraken's spot market rates as an external reference for major fiat-anchored assets. This normalization step ensures consistency across DEX pools regardless of base-quote pair configuration. For example, a pool quoted in USDC is translated into a USD price using Kraken’s real-time USDC/USD rate. This guarantees accurate aggregation and comparison of prices across heterogeneous liquidity sources.

***

### **CEX Pricing**

* Prices from multiple CEXs are fetched using aggregated market data.
* Each market is filtered by:
  * Matching `symbol/quote` pair (USD or USD-pegged)
  * Verified exchange support
* Aggregation is done via a **volume-weighted average** across available markets.

***

#### **Final Aggregated Price**

The final `aggregated.price` (as seen in `/v1/assets/ticker`) is computed as:

```ts
aggregatedPrice = weightedMean([dexPrice, cexPrice], weights = [dexVolume, cexVolume])
```

* `dexPrice` is the DEX-side weighted average across pools.
* `cexPrice` is the CEX-side volume-weighted average across markets.
* Weights are proportional to `h24UsdVolume`.


# APIs


# REST V1


# Assets

This section describes all ressources related to assets supported in the API

This API is still under developement


# Get Supported Assets

### **Description**

Retrieve the full list of supported assets indexed by Aleno.\
Each asset includes its canonical symbol and all known on-chain token addresses across supported chains.

{% hint style="info" %}
This endpoint is under development, additional metadata will be added to the assets.
{% endhint %}

This endpoint is useful for resolving symbols to chain-specific token addresses, validating availability, and constructing queries for endpoints like `/ticker`, `/search`, and `/state`.

If an asset is currently not supported, feel free to add it using [Add New Asset](/apis/rest-v1/assets/add-new-asset)

### **URL**

```bash
GET https://pricing.aleno.ai/v1/assets
```

### **Headers**

```http
x-api-key: your-api-key
```

### **Query Parameters**

| Name   | Type   | Required | Description                                                              |
| ------ | ------ | -------- | ------------------------------------------------------------------------ |
| symbol | string | No       | Filter by asset symbol (e.g., `WETH`, `AAVE`, `USDC`). Case-insensitive. |

If `symbol` is omitted, all assets are returned.

### **Response**

Returns one or more [asset ](https://docs.aleno.ai/apis/rest-v1/assets/pages/lip9iO15MXczc0On422A#id-1.-asset)entries, each including the canonical symbol and a list of token contract addresses across supported chains.

### **Example Request (All Assets)**

```bash
GET https://pricing.aleno.ai/v1/assets
```

### **Example Request (Single Asset)**

```bash
GET https://pricing.aleno.ai/v1/assets?symbol=WETH
```

### **Example Response**

```json
jsonCopierModifier{
  "data": [
    {
      "symbol": "WETH",
      "tokenMapping": [
        {
          "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
          "chainId": "eth"
        },
        {
          "address": "0x4200000000000000000000000000000000000006",
          "chainId": "opt"
        },
        {
          "address": "0x4200000000000000000000000000000000000006",
          "chainId": "base"
        },
        {
          "address": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
          "chainId": "arb"
        }
      ]
    }
  ]
}
```


# Add New Asset

### **Description**

Registers a new asset in the system using a valid CoinGecko ID or manually defined asset.\
The endpoint enriches the asset with metadata and auto-discovers associated DEX pools and CEX markets. The new asset becomes queryable via other endpoints (e.g. ticker, pool state) within 30 seconds to 3 minutes.

### **URL**

```bash
POST https://pricing.aleno.ai/v1/assets
```

### **Headers**

```http
x-api-key: your-api-key
Content-Type: application/json
```

### **Request Body**

| Field       | Type   | Required | Description                                                                                                               |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| coingeckoId | string | Optional | CoinGecko ID of the asset (e.g. `bitcoin`, `wrapped-bitcoin`). This ID is used to fetch token metadata and platform info. |
| asset       | object | Optional | <p>Manually defined asset. see example below<br><br><br><br></p>                                                          |

### **Example Query**&#x20;

**With coingecko ID**

```bash
curl -X POST https://pricing.aleno.ai/v1/assets \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "coingeckoId": "flare-networks"
  }'
```

**With manually defined asset (sylbol and tokenMapping)**

```bash
curl -X POST https://pricing.aleno.ai/v1/assets \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "symbol": "USDE",
    "tokenMapping": [
      {
        "address": "0x4c9edd5852cd905f086c759e8383e09bff1e68b3",
        "chainId": "eth"
      },
      {
        "address": "DEkqHyPN7GMRJ5cArtQFAWefqbZb33Hyf6s5iCwjEonT",
        "chainId": "solana"
      }
    ]
  }'
```

### **Responses**

**✅ Success (HTTP 200)**

Asset was added successfully, along with newly discovered pools and/or CEX data.

```json
{
  "status": "success",
  "successMessage": "SUCCESS: new asset WBTC successfully added and should be available within 30 seconds for API. New pools for this assets: 12. New CEX data for this asset: 1."
}
```

**✅ Accepted (HTTP 202)**

If process is taking more than 20 seconds, you will receive a message that indicates your request is still being processed.

```json
{
  "status": "pending",
  "successMessage": "PENDING: Your request to add a new asset is being processed. Adding a new asset can take up to 3 minutes in worst case, you can check at https://pricing.aleno.ai/v1/assets to see available assets and check if requested asset has been added."
}

```

**⚠️ Conflict (HTTP 409)**

The asset already exists in the system.

```json
{
  "status": "failed",
  "errorMessage": "FAILED: Asset WBTC already exists."
}
```

**❌ Validation Error (HTTP 400)**

Missing or invalid `coingeckoId`.

```json
{
  "status": "failed",
  "errorMessage": "FAILED: \"coingeckoId\" is required"
}
```

**❌ External API Failure / Internal Error (HTTP 500)**

CoinGecko fetch failed, pool discovery failed, or internal logic failed.

```json
{
  "status": "failed",
  "errorMessage": "FAILED: failed to get coingecko coin for id: wrapped-bitcoin. Coingecko API returned HTTP status code 404"
}
```

or

```json
{
  "status": "failed",
  "errorMessage": "FAILED: attempt to add new asset WBTC failed: failed to find pools for this token and no centralized exchange data found for this asset."
}
```


# Get Tickers

### Description

Retrieve the latest aggregated pricing and volume information for a specific ticker symbol.&#x20;

{% hint style="warning" %}
Only USD quotes are supported for now
{% endhint %}

### **URL**

```bash
GET https://pricing.aleno.ai/v1/assets/ticker?symbol={symbol}
```

### **Headers**

```http
x-api-key: your-api-key
```

### **Query Parameters**

| Name   | Type   | Required | Description                                                |
| ------ | ------ | -------- | ---------------------------------------------------------- |
| symbol | string | Yes      | The asset pair in `BASE/QUOTE` format. Example: `WBTC/USD` |

### **Response**

Returns a [ticker ](https://docs.aleno.ai/apis/rest-v1/assets/pages/lip9iO15MXczc0On422A#id-2.-ticker)object with pricing data aggregated from centralized (CEX) and decentralized (DEX) sources.

#### **Example Response**

```json
{
  "data": {
    "id": "WBTC/USD",
    "aggregated": {
      "price": 87107.08029830185,
      "h24UsdVolume": 295895764.524683
    },
    "cex": {
      "price": 87095.0654483101,
      "h24UsdVolume": 18124441.389037095
    },
    "dex": {
      "price": 87107.86426131867,
      "h24UsdVolume": 277771323.1356459,
      "usdTvl": 695400833.3529233
    }
  }
}
```

### Errors

* `400` Invalid `symbol` format. Expected `BASE/QUOTE` (example: `WBTC/USD`).
* `401` Missing API key (`x-api-key` header).
* `403` Invalid API key.
* `404` Ticker not found.
* `429` Rate limit exceeded for this route and API key.


# Pools


# Get state

### **Description**

Retrieve real-time state data for a specific on-chain liquidity pool, including token balances, USD valuations, 24-hour volume, and derived price ratios.\
Supports all pools indexed by Aleno across supported protocols and chains.

### **URL**

```bash
GET https://pricing.aleno.ai/v1/pools/state?address={poolAddress}&chainId={chainId}
```

### **Headers**

```http
x-api-key: your-api-key
```

### **Query Parameters**

| Name    | Type   | Required | Description                                                                                 |
| ------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| address | string | Yes      | Pool contract address                                                                       |
| chainId | string | Yes      | Chain identifier (e.g. `eth`, `arbitrum`, `bsc`, `base`, etc.). Must be supported by Aleno. |

### **Response**

Returns a real-time [pool state](https://docs.aleno.ai/apis/rest-v1/pools/pages/lip9iO15MXczc0On422A#id-3.-poolstate) object with pricing information for the specified liquidity pool, including TVL, token composition, 24-hour volume, and token-to-token price conversion.

### **Example Response**

```json
{
  "data": {
    "chainId": "eth",
    "address": "0xa43fe16908251ee70ef74718545e4fe6c5ccec9f",
    "protocol": "uniswap_v2",
    "usdTvl": 35379023.133415,
    "h24UsdVolume": 2732604.03634897,
    "tokens": [
      {
        "symbol": "PEPE",
        "address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
        "decimals": 18,
        "tvl": 2114257763951.88,
        "usdTvl": 17688809.9671931,
        "h24Volume": 161025927558.825,
        "h24UsdVolume": 1347213.70352451,
        "priceUsd": 0.000008366439640798
      },
      {
        "symbol": "WETH",
        "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "decimals": 18,
        "tvl": 8752.80822042656,
        "usdTvl": 17690213.1662219,
        "h24Volume": 685.466917764405,
        "h24UsdVolume": 1385390.33282446,
        "priceUsd": 2021.09
      }
    ],
    "pairs": [
      {
        "base": "PEPE",
        "quote": "WETH",
        "baseToQuotePrice": 4.13989645428388e-9,
        "quoteToBasePrice": 241551935.185534,
        "h24UsdVolume": 2732604.03634897
      }
    ]
  }
}
```

### Errors

This endpoint may return:

* `400` Invalid query parameters (e.g. malformed `address`, unsupported/invalid `chainId` format).
* `401` Missing API key. Provide it via `x-api-key` header.
* `403` Invalid API key.
* `404` Pool not found for the provided `address` and `chainId`.
* `429` Rate limit exceeded for this route and API key.

Example `429`:


# Search Pools by Symbol Pair

### **Description**

Discover all known liquidity pools across all supported chains and DEX protocols for a specific token pair, such as `SOL/USDC`.\
Supports optional filtering by 24h volume or TVL in USD and chainId.

{% hint style="info" %}

* This endpoint only supports on-chain assets.
* Fiat currencies like USD are not present on-chain as standalone assets, so queries using fiat as a quote (e.g., SOL/USD) will return no results.
* To get USD-denominated quotes, see[Get Tickers](/apis/rest-v1/assets/get-tickers)
  {% endhint %}

### **URL**

```bash
GET https://pricing.aleno.ai/v1/pools/search?symbol={base}/{quote}
```

### **Headers**

```http
x-api-key: your-api-key
```

### **Query Parameters**

| Name         | Type   | Required | Description                                                                                                                                 |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| symbol       | string | Yes      | Token pair in the format `BASE/QUOTE` (e.g., `SOL/USDC`). Case-insensitive.                                                                 |
| minVolumeUsd | number | No       | Filters out pools with 24h volume below this USD threshold. Default: `0`.                                                                   |
| minUsdTvl    | number | No       | Filters out pools with TVL below this USD threshold. Default: `0`.                                                                          |
| chainId      | string | No       | Filters results to pools on a specific chain (e.g., `1` for Ethereum, `137` for Polygon). If omitted, pools from all chains are considered. |

### **Response**

Returns an array of real-time [pool state](https://docs.aleno.ai/apis/rest-v1/pools/pages/lip9iO15MXczc0On422A#id-3.-poolstate) objects, each representing a matching pool across chains and protocols.

### **Example Request**

```bash
GET https://pricing.aleno.ai/v1/pools/search?symbol=SOL/USDC&minUsdTvl=100000
```

***

### **Example Response**

```json
{
  "data": [
    {
      "chainId": "solana",
      "address": "8sLbNZoA1cfnvMJLPfp98ZLAnFSYCFApfJKMbiXNLwxj",
      "protocol": "raydium-clmm",
      "usdTvl": 2451669.8364395,
      "h24UsdVolume": 10266629.1308575,
      "tokens": [
        {
          "symbol": "SOL",
          "address": "So11111111111111111111111111111111111111112",
          "decimals": 9,
          "tvl": 17166.280547238,
          "usdTvl": 2247534.07644117,
          "h24Volume": 38436.322725496,
          "h24UsdVolume": 5032362.41892493,
          "priceUsd": 130.92726
        },
        {
          "symbol": "USDC",
          "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "decimals": 6,
          "tvl": 204186.8067,
          "usdTvl": 204135.759998325,
          "h24Volume": 5235575.60583401,
          "h24UsdVolume": 5234266.71193255,
          "priceUsd": 0.99975
        }
      ],
      "pairs": [
        {
          "base": "SOL",
          "quote": "USDC",
          "baseToQuotePrice": 130.950983643172,
          "quoteToBasePrice": 0.00763644511999157,
          "h24UsdVolume": 10266629.1308575
        }
      ]
    },
    {
      "chainId": "solana",
      "address": "2QdhepnKRTLjjSqPL1PtKNwqrUkoLee5Gqs8bvZhRdMv",
      "protocol": "raydium-clmm",
      "usdTvl": 561792.073410444,
      "h24UsdVolume": 720872.896000079,
      "tokens": [
        {
          "symbol": "SOL",
          "address": "So11111111111111111111111111111111111111112",
          "decimals": 9,
          "tvl": 2241.559080991,
          "usdTvl": 293481.18860227,
          "h24Volume": 2695.08477448001,
          "h24UsdVolume": 352860.064990385,
          "priceUsd": 130.92726
        },
        {
          "symbol": "USDC",
          "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "decimals": 6,
          "tvl": 268377.979303,
          "usdTvl": 268310.884808174,
          "h24Volume": 368104.857224,
          "h24UsdVolume": 368012.831009694,
          "priceUsd": 0.99975
        }
      ],
      "pairs": [
        {
          "base": "SOL",
          "quote": "USDC",
          "baseToQuotePrice": 130.889201861653,
          "quoteToBasePrice": 0.00764004964333861,
          "h24UsdVolume": 720872.896000079
        }
      ]
    }
  ]
}
```


# RWAs


# Equities

Aleno provides real-time equity market data through a unified pricing infrastructure. The equities endpoints follow the same authentication,, and response standards as the Crypto pricing API

All endpoints require an API key passed via header.

***

### Get Supported Assets

Returns a list of all available assets.

```bash
curl -H "x-api-key: your-api-key" \
"https://pricing.aleno.ai/v1/equities/symbols"
```

#### Response

```json
{
  "data": [
    {
      "symbol": "QOMOU",
      "name": "Qomolangma Acquisition Corp.",
      "exchange": "NASDAQ",
      "type": "stock"
    },
    ...
  ],
  "meta": {
    "count": 26412,
    "supportedExchanges": {
      "US": [
        "NYSE",
        "NASDAQ",
        "AMEX"
      ],
      "KR": [
        "KSC",
        "KOSDAQ"
      ],
      "HK": [
        "HKSE"
      ]
    }
  }
}                    
```

#### Response fields

| Field    | Description                                               |
| -------- | --------------------------------------------------------- |
| symbol   | Ticker.                                                   |
| name     | Full legal or common name of the company/entity           |
| exchange | Primary exchange where the security is listed and traded. |
| type     | Asset type classification (stock, fund, etf, trust).      |

***

### Current Price

Returns the latest available current price for one or multiple equity symbols.

This endpoint is designed for real-time pricing, portfolio valuation, and oracle ingestion use cases.

#### Request (mutiple-assets)

```http
curl -H "x-api-key: your-api-key" \
"https://pricing.aleno.ai/v1/equities/quote?symbols=AAPL,MSFT,9961.HK"
```

#### **Request (single asset)**

```bash
curl -H "x-api-key: your-api-key" \
"https://pricing.aleno.ai/v1/equities/quote?symbols=9961.HK"
```

#### Request body

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| Symbol(s) | String | Yes      | Comma-separated list of equity symbols |

#### **Response**

```json
{
  "data": [
    {
      "symbol": "AAPL",
      "price": 255.78
    },
    {
      "symbol": "MSFT",
      "price": 401.32
    },
    {
      "symbol": "9961.HK",
      "price": 419.8
    }
  ]
}
```

#### **Response fields**

| Field  | Description                      |
| ------ | -------------------------------- |
| symbol | Exchange-qualified ticker symbol |
| price  | Current price                    |


# FX and metals

🚧 Coming Soon ...

### Description

Price feeds for currencies like CAD, EUR, JPY, GBP, USD, and others, including emerging market and commodity currencies.Forex List, Full Quote List, Full Quote, Forex Intraday, Forex Dails


# Economic Indicators

🚧 Coming Soon ...

###


# Websocket V1

WebSocket API Documentation for real time Tickers Monitoring

### **Overview**

This API allows clients to subscribe/unsubscribe to real-time market feeds over Socket.IO.Supported feed types:

* Crypto tickers via `subscribe_ticker / unsubscribe_ticker`
* Equities via `subscribe_equity / unsubscribe_equity`

Updates are currently emitted every 1 second for subscribed feeds. Each emitted record includes sentTimestampMs (server send timestamp in milliseconds).

### Authentication

A valid API key is required at connection time. Use either:

* auth.apiKey (recommended)
* x-api-key handshake header

If key is missing/invalid, connection is rejected with connect\_error (e.g. Missing or invalid API key.).

### WebSocket endpoint <a href="#websocket-endpoint" id="websocket-endpoint"></a>

WebSocket communication is implemented using a `socket.io` server, providing built-in support for automatic message compression and automatic reconnections, making client integration simpler and more reliable.

To connect, use the following WebSocket endpoint:

* **Server URL:** `https://pricing.aleno.ai`
* **Socket.IO path:** `/v1/socket`

Javascript Example (using `socket.io-client`):

```typescript
import { io } from 'socket.io-client';

const socket = io('https://pricing.aleno.ai', {
  path: '/v1/socket',
  auth: { apiKey: 'YOUR_API_KEY' },
  extraHeaders: { 'x-api-key': 'YOUR_API_KEY' }, // optional fallback
});
```

### Events

**Client -> Server**

* subscribe\_ticker (string\[], ack)
* unsubscribe\_ticker (string\[], ack)
* subscribe\_equity (string\[], ack)
* unsubscribe\_equity (string\[], ack)

**Server -> Client**

* new\_token\_states (crypto updates)
* new\_equity\_states (equities updates)

## Subscription behavior

* Symbols are normalized server-side (trim + uppercase).
* Unsupported symbols are rejected.
* Subscription acknowledgements can be:
* ok (all accepted),
* partial (some accepted, some rejected),
* error (request rejected, e.g. per-key feed limit exceeded).

### Acknowledgement payload

```json
{
  "status": "ok | partial | error",
  "involvedSubscriptions": ["AAPL", "MSFT"],
  "subscriptionsAfterUpdate": ["AAPL", "MSFT"],
  "rejectedSubscriptions": ["INVALID_SYMBOL"],
  "error": "Subscription limit reached. Contact us to increase limits."
}
```

Fields:

* status: operation result
* involvedSubscriptions: accepted symbols involved in the request
* subscriptionsAfterUpdate: current active subscriptions after processing
* rejectedSubscriptions (optional): unsupported/denied symbols
* error (optional): human-readable error for rejected operation

### Example: subscribe to crypto + equities

```typescript
import { io } from 'socket.io-client';

const socket = io('https://pricing.aleno.ai', {
  path: '/v1/socket',
  auth: { apiKey: 'YOUR_API_KEY' },
});

socket.on('connect', () => {
  socket.emit('subscribe_ticker', ['BTC/USD', 'ETH/USD'], (ack) => {
    console.log('ticker ack', ack);
  });

  socket.emit('subscribe_equity', ['AAPL', 'MSFT'], (ack) => {
    console.log('equity ack', ack);
  });
});

socket.on('new_token_states', (data) => {
  console.log('crypto updates', data);
});

socket.on('new_equity_states', (data) => {
  console.log('equity updates', data);
});

socket.on('connect_error', (err) => {
  console.error('Connection error:', err.message);
});
```

***

#### Unsubscribe example

```typescript
socket.emit('unsubscribe_ticker', ['BTC/USD'], (ack) => {
  console.log('unsubscribe ticker ack', ack);
});

socket.emit('unsubscribe_equity', ['MSFT'], (ack) => {
  console.log('unsubscribe equity ack', ack);
});
```

***

#### Payload notes

**`new_token_states`**

Array of crypto ticker state objects (existing ticker schema) with additional:

* sentTimestampMs: number

**`new_equity_states`**

Array of objects:

* sentTimestampMs: number
* symbol: string
* price: number

***

#### Limits

Per API key limits are enforced server-side (customer-specific configuration), including feed subscription limits.If a subscription exceeds your allowed limit, the server returns:

* `status: "error"`
* `error: "Subscription limit reached. Contact us to increase limits."`

***

#### Reconnection & resubscription

Socket.IO handles transport reconnection automatically, but clients should always reissue subscriptions on reconnect to guarantee continuity after disconnect/server restarts.socket.on('connect', () => {  // re-subscribe all required feeds here});

```typescript
socket.on('connect', () => {
  // re-subscribe all required feeds here
});
```


# Data Reference

This section documents the reusable data types returned by the Aleno Pricing API across all endpoints.

***

### **1. Asset**

```ts
type Asset = {
  symbol: string;
  tokenMapping: {
    chainId: string;
    address: string;
  }[];
};
```

* `symbol`: Canonical asset symbol (e.g., `WETH`, `AAVE`).
* `tokenMapping`: Array of chain-specific token contracts.

***

### **2. Ticker**

```ts
type Ticker = {
  id: string;
  aggregated: {
    price: number;
    h24UsdVolume: number;
  };
  cex: {
    price: number;
    h24UsdVolume: number;
  };
  dex: {
    price: number;
    h24UsdVolume: number;
    usdTvl: number;
  };
};
```

* `id`: Asset pair symbol in `BASE/QUOTE` format.
* `aggregated`: Aggregated price and volume across CEX + DEX.
* `cex`: Centralized exchange pricing data.
* `dex`: Decentralized exchange pricing and TVL data.

***

### **3. PoolState**

```ts
type PoolState = {
  chainId: string;
  address: string;
  protocol: string;
  usdTvl: number;
  h24UsdVolume: number;
  tokens: {
    symbol: string;
    address: string;
    decimals: number;
    tvl: number;
    usdTvl: number;
    h24Volume: number;
    h24UsdVolume: number;
    priceUsd: number;
  }[];
  pairs: {
    base: string;
    quote: string;
    baseToQuotePrice: number;
    quoteToBasePrice: number;
    h24UsdVolume: number;
  }[];
};
```

* `chainId`: Aleno chain ID (`eth`, `solana`, `arb`, etc.).
* `address`: Pool contract address.
* `protocol`: DEX protocol ID (e.g., `uniswap_v2`, `raydium-clmm`).
* `usdTvl`: Total value locked in USD.
* `h24UsdVolume`: 24-hour volume in USD for the pool.
* `tokens`: Array of tokens in the pool, with liquidity and pricing details.
* `pairs`: Derived price ratios between token pairs.