# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.w-chain.com/advanced-features/w-swap-trade-volume-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.