Public API

Base URL

https://suony.com/api/v1

Rules

• No auth. All endpoints are public.
• Rate limit: 120 requests / minute / IP. Exceed → 429 Too Many Requests.
• CORS: Access-Control-Allow-Origin: * — call from any browser origin.
• Cache: responses have Cache-Control: public, max-age=5, s-maxage=10. Don't poll faster than that; you'll just read cached data.
• Pagination: ?limit=N&offset=M on list endpoints. Default 50, max 200 (trades: max 500).

Endpoints

GET /characters

List characters with live stats. Sortable and filterable by category.

Query: sort = trending|top|new (default trending), category, limit, offset

curl 'https://suony.com/api/v1/characters?sort=top&limit=10'

{
  "characters": [{
    "id": 1, "slug": "choonsik", "name": "Choonsik", "ticker": "CHOON",
    "avatar_url": "/static/characters/choonsik.webp",
    "category": "Comedy",
    "contract_address": "0x...",
    "price": 0.00000161,
    "price_change_24h": 18.66,
    "market_cap": 1234.56,
    "progress_pct": 23.99,
    "fans": 1, "messages_24h": 8, "total_messages": 8,
    "total_burned": 2835664,
    "created_at": "2026-04-15T11:53:37Z"
  }],
  "count": 1, "limit": 10, "offset": 0, "sort": "top"
}

GET /characters/{slug}

Full details for one character including live price and social links.

curl https://suony.com/api/v1/characters/choonsik

GET /characters/{slug}/trades

Recent trades for one character. Ordered newest first. Includes trader username (if registered) and tx hash.

Query: limit (default 50, max 500)

curl 'https://suony.com/api/v1/characters/choonsik/trades?limit=20'

{
  "character_id": 1, "count": 20,
  "trades": [{
    "id": 15, "character_id": 1,
    "character_slug": "choonsik", "character_ticker": "CHOON",
    "type": "buy",
    "amount_usdc": 100, "amount_tokens": 65762328.34, "price": 0.00000161,
    "wallet": "0x...", "username": "theevoq",
    "tx_hash": "0x...",
    "created_at": "2026-04-19T14:00:00Z"
  }]
}

GET /characters/{slug}/sparkline

20-point downsampled price series over the last 24h. Use for sparkline charts.

curl https://suony.com/api/v1/characters/choonsik/sparkline

{
  "character_id": 1, "character_slug": "choonsik", "window": "24h",
  "points": [0.00000135, 0.00000137, ..., 0.00000161]
}

GET /trades/recent

Global trade feed across all characters. Newest first.

Query: limit (default 100, max 500)

curl 'https://suony.com/api/v1/trades/recent?limit=50'

GET /kings/current

Live King of the Hill — character with the most burned messages in the trailing 24h, plus top-3 runners-up.

curl https://suony.com/api/v1/kings/current

{
  "king": {
    "character_id": 1, "character_name": "Choonsik",
    "character_slug": "choonsik", "character_ticker": "CHOON",
    "avatar_url": "/static/characters/choonsik.webp",
    "burn_usd": 0.10, "messages_count": 10
  },
  "runners_up": [...]
}

GET /kings/leaderboard

Hall of Fame — characters ranked by total crowns earned (days as King).

Query: limit (default 50, max 200)

curl 'https://suony.com/api/v1/kings/leaderboard?limit=20'

GET /stats

Platform-level aggregates: total characters, trades, 24h volume, messages, burned USD, active characters in 24h.

curl https://suony.com/api/v1/stats

{
  "total_characters": 1,
  "total_trades": 15,
  "total_volume_usd_24h": 110,
  "total_messages": 70,
  "total_burned_usd": 0.70,
  "active_characters_24h": 1
}

Errors

Errors return JSON with HTTP status:

{"error": "character not found"}

• 404 — slug doesn't exist
• 429 — rate limit exceeded
• 500 — server error (retry with backoff)