> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eluup.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 API Reference

> Complete request and response reference for ELUUP x402 market data APIs.

Complete request, response, field, and endpoint reference for ELUUP's x402 market data APIs.

## Common Response Structure

All successful and application-level-error API responses use the standard `{ success, data, error }` wrapper described below.

All successful and application-level-error API responses use the following wrapper:

```json theme={null}
{
  "success": true,
  "data": {},
  "error": null
}
```

### Response fields

| Field     | Type               | Description                                                           |
| --------- | ------------------ | --------------------------------------------------------------------- |
| `success` | `boolean`          | Indicates whether the API operation succeeded                         |
| `data`    | `object` \| `null` | API-specific response data. Always `null` when `success` is `false`.  |
| `error`   | `string` \| `null` | Human-readable error message. Always `null` when `success` is `true`. |

This shape is symmetric and predictable: exactly one of `data` / `error` is populated, and the other is always `null` — never omitted. You can safely read `response.data.data` and `response.data.error` without checking for key presence first.

For successful responses:

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      /* ... */
    ]
  },
  "error": null
}
```

For application-level errors:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "error message"
}
```

<Note>
  **Note:** This wrapper applies to responses generated by the route handlers (`200`, `400`, `404`, `502`). It does **not** apply to `402` responses — those are generated entirely by the x402 payment middleware and use a different structure. See [HTTP 402 — Payment Required](/x402/payment-flow#http-402-payment-required).
</Note>

***

## Token Identifier

The token-batch APIs accept a token `identifier`, which can be:

| Format               | Example                                      |
| -------------------- | -------------------------------------------- |
| EVM contract address | `0x1bc0c42215582d5a085795f4badbac3ff36d1bcb` |
| CoinGecko coin ID    | `clanker`                                    |
| Ticker symbol        | `ETH`, `USDC`                                |

Identifiers are matched case-insensitively — `mcade` and `MCADE` are treated as the **same token** and will trigger the duplicate-token rejection if both are included in one request.

***

## POST /v1/token-signals

Returns trading signals for one or more tokens.

**Payment:** `$0.05 × number of tokens` · scheme `exact` · network `eip155:8453` · max batch `5`

### Request

```json theme={null}
{
  "tokens": [{ "identifier": "clanker", "limit": 10 }]
}
```

| Field                 | Type    | Required | Notes                                                                        |
| --------------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `tokens`              | array   | yes      | 1–5 items, no duplicates                                                     |
| `tokens[].identifier` | string  | yes      | EVM address, CoinGecko ID, or ticker                                         |
| `tokens[].limit`      | integer | no       | Default `10`, min `1`, max `100`. Number of signals to return, newest first. |

### Successful response — 200 OK

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "tokenAddress": "0x1bc0c42215582d5a085795f4badbac3ff36d1bcb",
        "tokenSymbol": "clanker",
        "strategy": "7/177 SMA Crossover (5-min timeframe)",
        "signalCount": 1,
        "signals": [
          {
            "signal": "SELL",
            "reason": "SELL Signal: Profit target reached or Fast SMA crossed below Slow SMA on shorter timeframes.",
            "signalPriceEth": 0.01028882885686473,
            "signalPriceUsd": 25.192454676754714,
            "signalPriceFormatted": "$2448.5250 (0.010289 ETH)",
            "previousShortSMA": 0.005095313198738749,
            "previousLongSMA": 0.0052186062982741,
            "crossoverDetected": false,
            "consecutiveGreenCandles": 0,
            "createdAt": "2026-06-22T06:24:25.565Z"
          }
        ]
      }
    ]
  },
  "error": null
}
```

#### `data.results[]`

| Field          | Type      | Description                  |
| -------------- | --------- | ---------------------------- |
| `tokenAddress` | `string`  | EVM contract address on Base |
| `tokenSymbol`  | `string`  | Token ticker symbol          |
| `strategy`     | `string`  | Signal generation strategy   |
| `signalCount`  | `integer` | Number of returned signals   |
| `signals`      | `array`   | Signal events, newest first  |

#### `data.results[].signals[]`

| Field                     | Type              | Description                                   |
| ------------------------- | ----------------- | --------------------------------------------- |
| `signal`                  | enum              | `BUY`, `SELL`, `WAITING FOR SIGNAL`, or `ALL` |
| `reason`                  | `string`          | Explanation for the signal                    |
| `signalPriceEth`          | `number`          | Signal price in ETH                           |
| `signalPriceUsd`          | `number`          | Signal price in USD                           |
| `signalPriceFormatted`    | `string`          | Human-readable price (USD and ETH)            |
| `createdAt`               | ISO 8601 datetime | Signal creation timestamp                     |
| `previousShortSMA`        | `number \| null`  | Previous short SMA value                      |
| `previousLongSMA`         | `number \| null`  | Previous long SMA value                       |
| `crossoverDetected`       | `boolean`         | Whether an SMA crossover was detected         |
| `consecutiveGreenCandles` | `integer`         | Number of consecutive green candles           |

***

## POST /v1/token-prices

Returns current token prices in ETH and USD.

**Payment:** `$0.03 × number of tokens` · scheme `exact` · network `eip155:8453` · max batch `5`

### Request

```json theme={null}
{ "tokens": [{ "identifier": "ETH" }] }
```

### Successful response — 200 OK

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "tokenAddress": "0x...",
        "symbol": "USDC",
        "currentPriceEth": 0.0003,
        "currentPriceUsd": 1.02
      }
    ]
  },
  "error": null
}
```

#### `data.results[]`

| Field             | Type     | Description                                       |
| ----------------- | -------- | ------------------------------------------------- |
| `tokenAddress`    | `string` | EVM contract address on Base                      |
| `symbol`          | `string` | Token ticker symbol                               |
| `currentPriceEth` | `number` | Current price in ETH                              |
| `currentPriceUsd` | `number` | Current price in USD (`ETH price × ETH/USD rate`) |

### Backend error — 502 Bad Gateway

If the underlying price logic fails, the endpoint returns `502` using the standard response wrapper (`success: false`).

***

## POST /v1/signal-history

Returns historical trading signals for one or more tokens.

**Payment:** `$0.05 × number of tokens` · scheme `exact` · network `eip155:8453` · max batch `5`

### Request

```json theme={null}
{
  "tokens": [{ "identifier": "clanker" }],
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-03-31T23:59:59Z",
  "signalType": "ALL"
}
```

| Field        | Type              | Required | Notes                                                                                  |
| ------------ | ----------------- | -------- | -------------------------------------------------------------------------------------- |
| `tokens`     | array             | yes      | 1–5 items, no duplicates                                                               |
| `startDate`  | ISO 8601 datetime | no       | Inclusive lower bound. Omit for no lower bound.                                        |
| `endDate`    | ISO 8601 datetime | no       | Inclusive upper bound. Omit for no upper bound. If both given, `startDate <= endDate`. |
| `signalType` | enum              | no       | `BUY`, `SELL`, `WAITING FOR SIGNAL`, `ALL` (default)                                   |

### Successful response — 200 OK

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "tokenAddress": "0x...",
        "tokenSymbol": "clanker",
        "strategy": "7/177 SMA Crossover (5-min timeframe)",
        "signalCount": 1,
        "signals": [
          {
            "signal": "SELL",
            "reason": "...",
            "signalPriceEth": 0.0102,
            "signalPriceUsd": 25.19,
            "signalPriceFormatted": "$2448.5250 (0.010289 ETH)",
            "previousShortSMA": 0.00509,
            "previousLongSMA": 0.00521,
            "crossoverDetected": false,
            "consecutiveGreenCandles": 0,
            "createdAt": "2026-06-22T06:24:25.565Z"
          }
        ]
      }
    ]
  },
  "error": null
}
```

`data.results[]` has the same shape as `/v1/token-signals`. `signalCount` is capped at 100.

***

## POST /v1/token-win-rate

Returns the average win rate for one or more tokens.

**Payment:** `$0.03 × number of tokens` · scheme `exact` · network `eip155:8453` · max batch `5`

### Request

```json theme={null}
{ "tokens": [{ "identifier": "ETH" }] }
```

### Successful response — 200 OK

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      { "tokenAddress": "0x...", "tokenSymbol": "ETH", "winRate": 72.5 }
    ]
  },
  "error": null
}
```

#### `data.results[]`

| Field          | Type             | Description                                                 |
| -------------- | ---------------- | ----------------------------------------------------------- |
| `tokenAddress` | `string`         | EVM contract address on Base                                |
| `tokenSymbol`  | `string`         | Token ticker symbol                                         |
| `winRate`      | `number \| null` | Average win-rate percentage. `null` when insufficient data. |

***

## POST /v1/token-avg-prices

Returns average buy and sell prices across agents.

**Payment:** `$0.02 × number of tokens` · scheme `exact` · network `eip155:8453` · max batch `5`

### Request

```json theme={null}
{ "tokens": [{ "identifier": "ETH" }] }
```

### Successful response — 200 OK

```json theme={null}
{
  "success": true,
  "data": {
    "results": [
      {
        "tokenAddress": "0x...",
        "tokenSymbol": "ETH",
        "averageBuyPriceETH": 0.01,
        "averageBuyPriceUSD": 25,
        "averageSellPriceETH": 0.012,
        "averageSellPriceUSD": 30
      }
    ]
  },
  "error": null
}
```

#### `data.results[]`

| Field                 | Type             | Description                         |
| --------------------- | ---------------- | ----------------------------------- |
| `tokenAddress`        | `string`         | EVM contract address on Base        |
| `tokenSymbol`         | `string`         | Token ticker symbol                 |
| `averageBuyPriceETH`  | `number \| null` | `null` if no valid buy data exists  |
| `averageBuyPriceUSD`  | `number \| null` | `null` if no valid buy data exists  |
| `averageSellPriceETH` | `number \| null` | `null` if no valid sell data exists |
| `averageSellPriceUSD` | `number \| null` | `null` if no valid sell data exists |

***

## POST /v1/top-performers

Returns the highest-performing tokens by win rate or ROI. Not a batch endpoint — no `tokens` array required.

**Payment:** `$0.06 per request` (fixed, independent of `limit`) · scheme `exact` · network `eip155:8453`

### Request

```json theme={null}
{ "sortBy": "winRate", "limit": 300 }
```

| Field    | Type    | Required | Notes                             |
| -------- | ------- | -------- | --------------------------------- |
| `sortBy` | enum    | yes      | `winRate` or `ROI`                |
| `limit`  | integer | no       | Default `300`, min `1`, max `300` |

### Successful response — 200 OK

```json theme={null}
{
  "success": true,
  "data": {
    "tokens": [
      {
        "tokenAddress": "0x...",
        "symbol": "ETH",
        "name": "Ethereum",
        "network": "Base",
        "winRate": 75.5,
        "ROI": 32.4,
        "agentCount": 12
      }
    ]
  },
  "error": null
}
```

> The response property is exactly `ROI` (capitalized).

***

## POST /v1/aggregate-metrics

Returns aggregate trading metrics across the platform. No request parameters.

**Payment:** `$0.06 per request` · scheme `exact` · network `eip155:8453`

### Request

```json theme={null}
{}
```

### Successful response — 200 OK

```json theme={null}
{
  "success": true,
  "data": {
    "totalAgents": 10,
    "activeAgents": 7,
    "totalTrades": 1250,
    "totalBuyETH": 15.5,
    "totalBuyUSD": 52000,
    "totalSellETH": 18.2,
    "totalSellUSD": 61000,
    "realizedProfitETH": 2.7,
    "realizedProfitUSD": 9000,
    "unrealizedProfitETH": 0.8,
    "unrealizedProfitUSD": 2700,
    "totalProfitableTrades": 800,
    "winRate": 64
  },
  "error": null
}
```

Profit fields (`realizedProfit*`, `unrealizedProfit*`) can be negative — no non-negative constraint is applied to them.

***

## POST /v1/supported-tokens

Returns the tokens supported by the platform. **Free — no x402 payment required.**

### Request

```json theme={null}
{ "limit": 100 }
```

`limit`: integer, optional, default `100`, min `1`, max `500`.

### Successful response — 200 OK

```json theme={null}
{
  "success": true,
  "data": {
    "total": 100,
    "tokens": [
      {
        "tokenAddress": "0x...",
        "symbol": "USDC",
        "name": "USD Coin",
        "network": "Base",
        "logo": "https://...",
        "marketCap": 123456789,
        "marketCapRank": 12,
        "poolAddress": "0x...",
        "agentCount": 25
      }
    ]
  },
  "error": null
}
```

***

## Response Data Shape Summary

Do not assume every endpoint uses `data.results`.

| Endpoint                | Data structure                 |
| ----------------------- | ------------------------------ |
| `/v1/token-signals`     | `data.results[]`               |
| `/v1/token-prices`      | `data.results[]`               |
| `/v1/signal-history`    | `data.results[]`               |
| `/v1/token-win-rate`    | `data.results[]`               |
| `/v1/token-avg-prices`  | `data.results[]`               |
| `/v1/top-performers`    | `data.tokens[]`                |
| `/v1/aggregate-metrics` | `data` (flat object)           |
| `/v1/supported-tokens`  | `data.total` + `data.tokens[]` |

Preserve this distinction when building typed clients or SDK wrappers.

***

**x402 docs:** [Overview](/x402) · [Quickstart](/x402/quickstart) · [Payment Flow](/x402/payment-flow) · [API Reference](/x402/api-reference) · [Errors & Troubleshooting](/x402/errors) · [Examples](/x402/examples)