x402 API Reference

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:

{
  "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:

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

For application-level errors:

{
  "success": false,
  "data": null,
  "error": "error message"
}

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.

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

{
  "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

{
  "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

{ "tokens": [{ "identifier": "ETH" }] }

Successful response — 200 OK

{
  "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

{
  "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

{
  "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

{ "tokens": [{ "identifier": "ETH" }] }

Successful response — 200 OK

{
  "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

{ "tokens": [{ "identifier": "ETH" }] }

Successful response — 200 OK

{
  "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

{ "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

{
  "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

{}

Successful response — 200 OK

{
  "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

{ "limit": 100 }

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

Successful response — 200 OK

{
  "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 · Quickstart · Payment Flow · API Reference · Errors & Troubleshooting · Examples

​Common Response Structure

​Response fields

​Token Identifier

​POST /v1/token-signals

​Request

​Successful response — 200 OK

​data.results[]

​data.results[].signals[]

​POST /v1/token-prices

​Request

​Successful response — 200 OK

​data.results[]

​Backend error — 502 Bad Gateway

​POST /v1/signal-history

​Request

​Successful response — 200 OK

​POST /v1/token-win-rate

​Request

​Successful response — 200 OK

​data.results[]

​POST /v1/token-avg-prices

​Request

​Successful response — 200 OK

​data.results[]

​POST /v1/top-performers

​Request

​Successful response — 200 OK

​POST /v1/aggregate-metrics

​Request

​Successful response — 200 OK

​POST /v1/supported-tokens

​Request

​Successful response — 200 OK

​Response Data Shape Summary

Common Response Structure

Response fields

Token Identifier

POST /v1/token-signals

Request

Successful response — 200 OK

`data.results[]`

`data.results[].signals[]`

POST /v1/token-prices

Request

Successful response — 200 OK

`data.results[]`

Backend error — 502 Bad Gateway

POST /v1/signal-history

Request

Successful response — 200 OK

POST /v1/token-win-rate

Request

Successful response — 200 OK

`data.results[]`

POST /v1/token-avg-prices

Request

Successful response — 200 OK

`data.results[]`

POST /v1/top-performers

Request

Successful response — 200 OK

POST /v1/aggregate-metrics

Request

Successful response — 200 OK

POST /v1/supported-tokens

Request

Successful response — 200 OK

Response Data Shape Summary