API Reference

REST API endpoints for integrating with AgoraX. All public endpoints use the /api/v1 prefix.

Base URL

https://agorax.win/api/v1

All endpoints are rate limited to 300 req/min per IP per endpoint.

GET/v1/stats300 req/min

Protocol-wide aggregate statistics.

Example Request

GET /api/v1/stats

Try it

Response

{
  "success": true,
  "data": {
    "protocol": {
      "total_users": 150,
      "total_xp_issued": 125000,
      "total_trades": 1200,
      "total_volume_usd": 450000.00,
      "total_orders_created": 800,
      "fill_rate_percent": 65.5
    },
    "orders": {
      "total": 800,
      "by_status": { "active": 120, "cancelled": 80, "completed": 600 }
    }
  }
}

GET/v1/orders300 req/min

List and search orders with filters and pagination. Useful for aggregators looking for fillable orders.

Query Parameters

Parameter	Type	Description
status	string	Filter: active, cancelled, completed (or 0, 1, 2)
maker	string	Filter by maker wallet address (0x...)
sell_token	string	Filter by sell (from) token ticker, e.g. `HEX` (case-insensitive)
buy_token	string	Filter by buy (to) token ticker, e.g. `PLS` (case-insensitive)
has_fills	boolean	Only orders that have been partially or fully filled
min_fills	number	Minimum fill count
sort	string	Sort by: created_at, order_id, fill_percentage, total_fills, updated_at (default: created_at)
order	string	Sort order: asc or desc (default: desc)
limit	number	Max results (default: 50, max: 200)
offset	number	Pagination offset

Example Requests

GET /api/v1/orders?status=active&limit=10

Try it

GET /api/v1/orders?status=active&sell_token=HEX&buy_token=PLS

Try it

GET/v1/orders/{orderId}300 req/min

Full order details including fill history, cancellation info, and proceeds claims.

Query Parameters

Parameter	Type	Description
include	string	Comma-separated: fills, cancellation, proceeds (default: all)
fills_limit	number	Max fills to return (default: 100, max: 500)

Example Request

GET /api/v1/orders/1

Try it

GET/v1/users/{address}300 req/min

Full user profile including stats, challenges, events, and orders.

Query Parameters

Parameter	Type	Description
include	string	Comma-separated: challenges, events, orders, daily, xp_breakdown (default: all)
events_limit	number	Max events to return (default: 50, max: 200)
orders_limit	number	Max orders to return (default: 50, max: 200)

Example Request

GET /api/v1/users/0x1F12DAE5450522b445Fe1882C4F8D2Cf67B38a43

Try it

Response

{
  "success": true,
  "data": {
    "wallet_address": "0x1f12...",
    "stats": {
      "total_xp": 5250,
      "current_prestige": 2,
      "prestige_name": "Gamma",
      "total_orders_created": 23,
      "total_orders_filled": 18,
      "total_trades": 47,
      "total_volume_usd": 12500.50,
      "current_streak_days": 5
    },
    "challenges": {
      "total": 15,
      "by_prestige": { "0": [...], "1": [...] },
      "list": [...]
    },
    "orders": {
      "total": 23,
      "status_counts": { "active": 2, "completed": 18, "cancelled": 3 },
      "list": [...]
    }
  }
}

GET/v1/leaderboard300 req/min

Ranked users sorted by XP with full stats.

Query Parameters

Parameter	Type	Description
sort	string	Sort by: total_xp, total_trades, total_orders_created, total_orders_filled, current_prestige (default: total_xp)
order	string	Sort order: asc or desc (default: desc)
min_xp	number	Minimum XP threshold (default: 0)
min_trades	number	Minimum trades threshold (default: 0)
limit	number	Max results (default: 50, max: 200)
offset	number	Pagination offset

Example Request

GET /api/v1/leaderboard?limit=10&min_xp=100

Try it

Rate Limits

All endpoints are rate limited to 300 requests/minute per IP address per endpoint. Exceeding the limit returns a 429 response with Retry-After header.

Rate limit headers are included on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Responses

All endpoints return errors in a consistent format:

{
  "success": false,
  "error": "Error message here"
}

Status Codes

Code	Description
200	Success
400	Bad request (invalid parameters)
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Data Structures

Audit Report

{ "success": true, "data": { "protocol": { "total_users": 150, "total_xp_issued": 125000, "total_trades": 1200, "total_volume_usd": 450000.00, "total_orders_created": 800, "fill_rate_percent": 65.5 }, "orders": { "total": 800, "by_status": { "active": 120, "cancelled": 80, "completed": 600 } } } }

Parameter

Type

Description

status

string

Filter: active, cancelled, completed (or 0, 1, 2)

maker

string

Filter by maker wallet address (0x...)

sell_token

string

Filter by sell (from) token ticker, e.g. HEX (case-insensitive)

buy_token

string

Filter by buy (to) token ticker, e.g. PLS (case-insensitive)

has_fills

boolean

Only orders that have been partially or fully filled

min_fills

number

Minimum fill count

sort

string

Sort by: created_at, order_id, fill_percentage, total_fills, updated_at (default: created_at)

order

string

Sort order: asc or desc (default: desc)

limit

number

Max results (default: 50, max: 200)

offset

number

Pagination offset

Parameter

Type

Description

include

string

Comma-separated: fills, cancellation, proceeds (default: all)

fills_limit

number

Max fills to return (default: 100, max: 500)

Parameter

Type

Description

include

string

Comma-separated: challenges, events, orders, daily, xp_breakdown (default: all)

events_limit

number

Max events to return (default: 50, max: 200)

orders_limit

number

Max orders to return (default: 50, max: 200)

{ "success": true, "data": { "wallet_address": "0x1f12...", "stats": { "total_xp": 5250, "current_prestige": 2, "prestige_name": "Gamma", "total_orders_created": 23, "total_orders_filled": 18, "total_trades": 47, "total_volume_usd": 12500.50, "current_streak_days": 5 }, "challenges": { "total": 15, "by_prestige": { "0": [...], "1": [...] }, "list": [...] }, "orders": { "total": 23, "status_counts": { "active": 2, "completed": 18, "cancelled": 3 }, "list": [...] } } }

Parameter

Type

Description

sort

string

Sort by: total_xp, total_trades, total_orders_created, total_orders_filled, current_prestige (default: total_xp)

order

string

Sort order: asc or desc (default: desc)

min_xp

number

Minimum XP threshold (default: 0)

min_trades

number

Minimum trades threshold (default: 0)

limit

number

Max results (default: 50, max: 200)

offset

number

Pagination offset

Code

Description

200

Success

400

Bad request (invalid parameters)

404

Resource not found

429

Rate limit exceeded

500

Internal server error