> For the complete documentation index, see [llms.txt](https://docs.w-chain.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.w-chain.com/advanced-features/w-swap-trade-volume-api.md).

# W Swap Trade Volume API

### Endpoint

* Method: `GET`
* URL: `https://oracle.w-chain.com/api/w-swap/volume/:id`

### Purpose

* Returns the 24-hour aggregated USD volume for the specified trading pair.
* Also returns the pair name for convenience.

### Request

* Path parameter `id` (number): The `trade_pairs.id` of the pair.

#### Example

```
GET https://oracle.w-chain.com/api/w-swap/volume/2
```

### Success Response

* Status: `200 OK`
* Body:

```json
{
  "vol24h": 12345.67,
  "pair": "USDT/WCO"
}
```

#### Field Details

* `vol24h` (number): Total swap volume in USD over the past 24 hours.
* `pair` (string): The human-readable pair name from `trade_pairs.name`.

### Error Responses

* `400 Bad Request`: Missing `id` path parameter.

```json
{
  "statusCode": 400,
  "statusMessage": "Missing id parameter"
}
```

* `404 Not Found`: Pair not found (no matching `trade_pairs.id`).

```json
{
  "statusCode": 404,
  "statusMessage": "Pair not found"
}
```

### How Volume Is Calculated

* Source table: `trade_pair_swap_events`.
* Aggregation: Sum of `usd_value` for rows where:
  * `pair_id` equals the requested `id`.
  * `timestamp` is within the last 24 hours (`gt now - 24h` and `lte now`).
* USD valuation:
  * Stablecoins (`USDT`, `USDC`, and bridged variants) use a 1:1 USD mapping.
  * `WCO` is valued using its CoinGecko USD price.
  * Other tokens may currently resolve to `0` USD unless specifically supported.
* Caching: Results are cached for \~60 seconds to reduce load.

### `trade_pairs` Reference

The following pairs (from `trade_pairs`) are relevant for W Swap operations and USD valuation logic. The `usd_value_from` column indicates which token is used to determine USD value during swaps: `0` means `token0`, `1` means `token1`.

| id | name     | platform | pair\_address                              | token0\_address                            | token1\_address                            | token0\_decimals | token1\_decimals | fee | usd\_value\_from | wave\_pid |
| -- | -------- | -------- | ------------------------------------------ | ------------------------------------------ | ------------------------------------------ | ---------------- | ---------------- | --- | ---------------- | --------- |
| 1  | WAVE/WCO | 0        | 0x35264f0e8cd7a32341f47dbfbf2d85b81fd0ef0a | 0x42abfb13b4e3d25407ffa9705146b7cb812404a0 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 18               | 18               | 300 | 1                | 0         |
| 2  | USDT/WCO | 0        | 0xd4e9176d5189dbb24f40e5c6c45bb1682dcb3324 | 0x40cb2cccf80ed2192b53fb09720405f6fe349743 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 6                | 18               | 300 | 0                | 1         |
| 3  | USDC/WCO | 0        | 0x00d91ce419c068e36928fd8e9379b11d0011f052 | 0x643ec74ed2b79098a37dc45dcc7f1abfe2ade6d8 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 6                | 18               | 300 | 0                | 2         |
| 4  | SOL/WCO  | 0        | 0x9556d7afa868cb8b25657d34f3e0d46929f9d710 | 0xd4f93cacd6d607789c8ecf1dddeba8b0c4d915a8 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 18               | 18               | 300 | 1                | 4         |
| 5  | DOGE/WCO | 0        | 0x8b5f11ea77641b208fb53b4b91b2825db64b8c32 | 0x6cdfda79787caa4ad1a95456095bedc95abd2d75 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 8                | 18               | 300 | 1                | 5         |
| 6  | XRP/WCO  | 0        | 0x24f07de79398f24c9d4dd60a281a29843e43b7fd | 0x4560d5eb0c32a05fa59acd2e8d639f84a15a2414 | 0xedb8008031141024d50ca2839a607b2f82c1c045 | 18               | 18               | 300 | 1                | 6         |

#### Note on `wave_pid`

The `wave_pid` sequence skips `3` because in Wave Farm, pool ID `3` is a `WCO` Single Stake pool (not an LP pool). Therefore, LP-related pairs continue with `4`, `5`, `6`, etc.

### Usage Examples

#### cURL

```bash
curl -s "http://<host>/api/w-swap/volume/2"
```

#### JavaScript (fetch)

```js
// Fetch 24h volume for pair id 2 (USDT/WCO)
const resp = await fetch('/api/w-swap/volume/2');
if (!resp.ok) throw new Error('Request failed');
const data = await resp.json();
// data.vol24h is a number in USD; data.pair is the pair name
```

### Implementation Notes

* Internals use a 60-second cache to avoid excessive DB queries.
* If there are no swap events in the last 24h for the given pair, `vol24h` returns `0`.
* Authentication is not required for this public endpoint.

### Related Endpoints

* `GET /api/w-swap/lp-value/:id` — returns latest pair price and LP price (in USD).