Futarchy External API

A multi-aggregator DEX API for the Futarchy protocol that automatically discovers all DAOs, providing real-time pricing, volume, and trading data to CoinGecko, DexScreener, and other consumers.

Public API Documentation

Base URL: https://your-api-domain.com

CoinGecko Endpoints

GET `/api/tickers`

Returns all DAO tickers with pricing, volume, and liquidity information. Automatically discovers all DAOs from the Futarchy protocol.

Response:

[
  {
    "ticker_id": "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "base_currency": "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta",
    "target_currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "base_symbol": "ZKFG",
    "base_name": "ZKFG",
    "target_symbol": "USDC",
    "target_name": "USD Coin",
    "pool_id": "5FPGRzY9ArJFwY2Hp2y2eqMzVewyWCBox7esmpuZfCvE",
    "last_price": "0.081340728222",
    "base_volume": "30024.81040000",
    "target_volume": "2441.23456789",
    "liquidity_in_usd": "180138.45",
    "bid": "0.080934024581",
    "ask": "0.081747431863",
    "high_24h": "0.085000000000",
    "low_24h": "0.078000000000",
    "startDate": "2025-01-15"
  }
]

Fields:

Field	Description
`ticker_id`	Format `{BASE_MINT}_{QUOTE_MINT}`
`base_currency`	Base token mint address
`target_currency`	Quote token mint address (usually USDC)
`base_symbol` / `base_name`	Base token symbol and name (from on-chain metadata)
`target_symbol` / `target_name`	Quote token symbol and name
`pool_id`	DAO address
`last_price`	Current price (quote/base) from spot pool reserves
`base_volume` / `target_volume`	Rolling 24h trading volume
`liquidity_in_usd`	Total liquidity in USD
`bid` / `ask`	Spread-adjusted bid/ask prices
`high_24h` / `low_24h`	24h high/low (when available)
`startDate`	First trade date for the token

Volume source: futarchy.user_pool_spot_ohlcv in the served ETL DB. If the served DB is unavailable, the endpoint returns 503 instead of reporting zero volume.

CoinMarketCap Endpoints

Implements the DEX endpoints from [Section C] of CoinMarketCap's integration requirements. Served under /cmc/. The shapes mirror the CoinGecko adapter — CMC's DEX spec is field-for-field close — and both feeds are built from the same on-chain DAO discovery and rolling-24h ETL metrics.

API versioning. At CMC's request, every endpoint is also served under an explicit version prefix: /cmc/v1/summary, /cmc/v1/ticker, /cmc/v1/assets. The unversioned paths remain published as-is and are treated as the current (v1) contract — the two are URL aliases for the same handler, so they never diverge. A future breaking change would land under /cmc/v2/… while the existing paths keep serving v1.

/cmc/summary and /cmc/ticker carry 24h volume, so they require DATABASE_PG_URL and return 503 (never zero volume) if the served DB is unavailable. /cmc/assets is pure on-chain metadata and does not require it.

No dedicated auth: like every route, CMC reuses the shared rate-limit tiers — anonymous by IP, or the elevated per-key bucket when a trusted X-API-Key (TRUSTED_API_KEYS) is sent.

Set CMC_ALLOWED_MINTS (comma-separated base mints) to restrict the CMC feed to a specific set of tokens; empty (the default) serves every discovered DAO.

Every CMC feed keys its per-token data (24h volume/high/low, the 24h-ago reference reserves, and the /cmc/assets identity entry) by base mint, and the served-ETL tables carry no per-pool dimension. If two discovered markets ever share a base mint the numbers can't be attributed to the right pair, so all three endpoints fail closed with 503 (CMC_DUPLICATE_BASE_MINT) rather than serve one market's volume/price for another. The check runs after CMC_ALLOWED_MINTS, so narrowing the allowlist to a single side of a collision serves normally. In the futarchy model each DAO launches its own token, so this is an anomaly guard, not an expected path.

GET `/cmc/summary`

24h overview of every tradeable pair.

Response:

[
  {
    "trading_pairs": "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "base_currency": "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta",
    "quote_currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "type": "spot",
    "last_price": 0.081340728222,
    "lowest_ask": 0.081747431863,
    "highest_bid": 0.080934024581,
    "base_volume": 30024.8104,
    "quote_volume": 2441.23456789,
    "highest_price_24h": 0.085,
    "lowest_price_24h": 0.078,
    "price_change_percent_24h": 4.28
  }
]

base_currency / quote_currency are Solana mint (contract) addresses — the same ids /cmc/assets is keyed by, so CMC maps pairs → assets consistently.

highest_price_24h / lowest_price_24h are omitted when the ETL window has no real high/low.

price_change_percent_24h is the 24h price change in percent, computed from the AMM's exact price 24h ago. The FutarchyAMM price is a pure function of pool reserves, and reserves only change on a swap, so the reserves of the last swap ≥24h ago (futarchy.user_pool_swaps) are the pool's exact state 24h ago — priced through the same formula as last_price (a true mid-vs-mid comparison). It is omitted for a market younger than 24h (no swap before the cutoff), where the change is undefined — never fabricated as 0%. If the swaps source is briefly unavailable, the field is omitted for that response but price/volume still serve (unlike the volume source, whose absence returns 503).

GET `/cmc/ticker`

24h price and volume keyed by the BASE_QUOTE trading pair.

Response:

{
  "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta_EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": {
    "base_id": "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta",
    "quote_id": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "base_name": "ZKFG",
    "base_symbol": "ZKFG",
    "quote_name": "USD Coin",
    "quote_symbol": "USDC",
    "last_price": 0.081340728222,
    "base_volume": 30024.8104,
    "quote_volume": 2441.23456789,
    "isFrozen": 0
  }
}

GET `/cmc/assets`

Token identity keyed by mint address (both base and quote of every pair).

Response:

{
  "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta": {
    "name": "ZKFG",
    "symbol": "ZKFG",
    "contractAddress": "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta",
    "can_withdraw": "true",
    "can_deposit": "true",
    "maker_fee": 0.005,
    "taker_fee": 0.005
  }
}

DexScreener Adapter Endpoints

Implements the DexScreener Adapter Spec v1.1. All endpoints are served under /dexscreener/. Requires DATABASE_PG_URL to be configured for the served DB.

GET `/dexscreener/latest-block`

Returns the latest Solana slot for which swap data is available.

Response:

{
  "block": {
    "blockNumber": 312345678,
    "blockTimestamp": 1719500000
  }
}

GET `/dexscreener/asset?id=:mintAddress`

Returns token metadata for a given Solana mint address. Fetched from on-chain Metaplex Token Metadata.

Response:

{
  "asset": {
    "id": "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta",
    "name": "ZKFG",
    "symbol": "ZKFG",
    "metadata": {
      "decimals": "6"
    }
  }
}

GET `/dexscreener/pair?id=:daoAddress`

Returns immutable pair info for a DAO. Pair id is the dao_addr from the v0.6 indexer.

Response:

{
  "pair": {
    "id": "5FPGRzY9ArJFwY2Hp2y2eqMzVewyWCBox7esmpuZfCvE",
    "dexKey": "futarchy",
    "asset0Id": "ZKFHiLAfAFMTcDAuCtjNW54VzpERvoe7PBF9mYgmeta",
    "asset1Id": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "feeBps": 50,
    "createdAtBlockNumber": 290000000,
    "createdAtBlockTimestamp": 1710000000,
    "createdAtTxnId": "5xYz..."
  }
}

GET `/dexscreener/events?fromBlock=:slot&toBlock=:slot`

Returns swap events in the given Solana slot range (both inclusive). Events are queried from v0_6_spot_swaps in the external indexer DB.

Response:

{
  "events": [
    {
      "block": { "blockNumber": 312345678, "blockTimestamp": 1719500000 },
      "eventType": "swap",
      "txnId": "5xYz...",
      "txnIndex": 0,
      "eventIndex": 0,
      "maker": "UserWalletAddress...",
      "pairId": "5FPGRzY9ArJFwY2Hp2y2eqMzVewyWCBox7esmpuZfCvE",
      "asset1In": 100.5,
      "asset0Out": 1234.56,
      "priceNative": 0.08134
    }
  ]
}

Event mapping:

Buy (user sends USDC → receives token): asset1In + asset0Out
Sell (user sends token → receives USDC): asset0In + asset1Out
priceNative = price of asset0 (base token) in asset1 (USDC)
All amounts are decimalized (divided by 10^6)

Market Data

GET `/api/market-data?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&tokens=TOKEN1,TOKEN2`

Returns daily market data for the given date range, split by Futarchy AMM and Meteora sources.

Data source: both FutarchyAMM and Meteora data come from the unified futarchy.user_pool_daily ETL table in the served DB. The served DB is a hard dependency: if it's unreachable the endpoint returns 503 rather than reporting a DB outage as zero volume.

FutarchyAMM — source = 'futarchy_amm', pivoted into spot, conditional, and total daily columns. Response futarchyAMM.source is "etl-user-pool-daily".
Meteora — source = 'meteora', with the same daily accounting contract. Response meteora.source is "etl-meteora-daily".

Supply Endpoints

GET `/api/supply/:mintAddress`

Returns complete supply breakdown with allocation details for launchpad tokens.

GET `/api/supply/:mintAddress/total`

Returns total supply only (plain text number).

GET `/api/supply/:mintAddress/circulating`

Returns circulating supply — total minus team performance package.

Health & Admin

Endpoint	Description
`GET /health`	Liveness: process status and uptime (no dependency checks)
`GET /api/health`	Readiness: served DB connectivity, ETL data contract, and data freshness
`GET /metrics`	Prometheus metrics (HTTP, served-DB health gauges, heartbeat)

/api/health reports status: "degraded" (with a message) when the served DB is unreachable, the served-data contract check fails, or the freshness query fails.

Heartbeat: a background self-check runs every HEARTBEAT_INTERVAL_MS (default 1 min). It verifies served-DB connectivity, alerts when the newest swap is older than HEARTBEAT_MAX_DATA_AGE_SECONDS (default 6h — a stalled ETL with a healthy connection is still an outage), and re-checks the data contract every 10th tick. Failures push webhook alerts (with cooldowns) and update the futarchy_served_db_connected / futarchy_served_contract_ok / futarchy_served_data_age_seconds Prometheus gauges.

Installation

# Install dependencies
bun install

# Build the project
bun run build

# Start the server (runs build first)
bun run start

# Development with hot reload
bun run dev

Configuration

Create a .env file in the root directory (see example.env for reference):

Environment Variables

Variable	Description	Default
Solana
`SOLANA_RPC_URL` / `RPCPOOL_RPC_URL`	Solana RPC endpoint	`https://api.mainnet-beta.solana.com`
`SOLANA_WS_URL` / `RPCPOOL_WS_URL`	Solana WebSocket endpoint	`wss://api.mainnet-beta.solana.com`
Server
`PORT`	Server port	`3000`
`SERVER_REQUEST_TIMEOUT`	Request timeout (ms)	`300000`
`TRUST_PROXY_HOPS`	Reverse-proxy hops in front of the API (needed for per-IP rate limiting behind a LB)	`0`
`TRUSTED_API_KEYS`	Comma-separated allowlist of trusted partner keys	—
`TRUSTED_RATE_LIMIT_MAX`	Per-bucket request count per minute for trusted keys	`600`
`CACHE_TICKERS_TTL`	On-chain data cache TTL (ms)	`55000`
Served indexer DB (required — the only database this API uses)
`DATABASE_PG_URL`	Read-only connection to the served indexer DB (Meteora, tickers, DexScreener, first-trade-dates). Required — `/api/market-data`, `/api/tickers`, `/cmc/summary`, `/cmc/ticker`, and the DexScreener routes return 503 without it.	—
`DATABASE_PG_SSL`	Enable SSL (server cert verified against system CAs)	`false`
`DATABASE_PG_CA_CERT`	PEM CA cert content for private-CA verification	—
`DATABASE_PG_SSL_NO_VERIFY`	Explicit opt-out of TLS verification (stopgap only)	`false`
Heartbeat
`HEARTBEAT_INTERVAL_MS`	Background self-check cadence (0 disables)	`60000`
`HEARTBEAT_MAX_DATA_AGE_SECONDS`	Stale-data alert threshold (0 disables)	`21600`
Protocol
`PROTOCOL_FEE_RATE`	Protocol fee rate	`0.005` (0.5%)
`EXCLUDED_DAOS`	Comma-separated DAO addresses to exclude	—
`CMC_ALLOWED_MINTS`	Comma-separated base-mint allowlist for the `/cmc/*` routes; empty serves all. Validated at startup; if set but matching zero discovered DAOs, the CMC routes fail closed with 503.	—
Alerts
`ALERT_WEBHOOK_URL`	Telegram alert webhook URL	—
`ALERT_WEBHOOK_SECRET`	Webhook secret	—

Architecture

src/
├── app.ts                        # Express app setup & middleware
├── main.ts                       # API entry point (serves routes, no indexing workers)
├── runtime/
│   ├── services.ts               # API service composition
│   └── heartbeat.ts              # Background self-check (served DB, freshness, contract)
├── config.ts                     # Environment variables & configuration
├── routes/
│   ├── index.ts                  # Route registration
│   ├── coingecko.ts              # GET /api/tickers
│   ├── coinmarketcap.ts          # CoinMarketCap DEX adapter (summary/ticker/assets)
│   ├── dexscreener.ts            # DexScreener adapter (4 endpoints)
│   ├── market.ts                 # GET /api/market-data (user_pool ETL)
│   ├── supply.ts                 # GET /api/supply/*
│   ├── health.ts                 # Liveness + readiness checks
│   ├── metrics.ts                # Prometheus metrics
│   └── root.ts                   # GET / (API info)
├── services/
│   ├── futarchyService.ts        # On-chain DAO/pool/token data
│   ├── priceService.ts           # Price, spread, liquidity calculations
│   ├── externalDatabaseService.ts # Read-only served ETL DB connection (the only DB)
│   ├── solanaService.ts          # SPL token supply queries
│   ├── launchpadService.ts       # Token allocation breakdown
│   └── metricsService.ts         # Prometheus counters/histograms
├── types/
│   ├── coingecko.ts              # CoinGecko response types
│   ├── coinmarketcap.ts          # CoinMarketCap response types
│   └── dexscreener.ts            # DexScreener response types
├── middleware/
│   ├── errorHandler.ts           # Error handling & asyncHandler
│   └── requestId.ts              # Request ID injection
└── utils/                        # Logger, alerts, validation, scheduling

Data Pipeline

Sources (Dune fully removed)

The API process serves market data from the read-only served ETL DB:

/api/tickers reads rolling 24h metrics from futarchy.user_pool_spot_ohlcv.
/api/market-data reads FutarchyAMM and Meteora daily rows from futarchy.user_pool_daily.
DexScreener routes read raw indexed v0.6 swap/DAO tables from the same served DB.

The served ETL DB is the only database this API connects to (the legacy app DB is fully removed). The API does not start indexing, fetchers, rollups, or any schema setup — it is serve-only.

DexScreener Pipeline

The DexScreener adapter reads directly from the external indexer DB (v0_6_spot_swaps + v0_6_daos) and serves real-time swap events indexed by Solana slot. No intermediate aggregation — raw swap data mapped to the DexScreener schema.

Rate Limiting

Anonymous (default): 60 requests per minute per IP. Returns 429 Too Many Requests when exceeded.
- Behind a proxy/load balancer, set TRUST_PROXY_HOPS to the real hop count — otherwise every anonymous client resolves to the proxy's IP and shares a single bucket.
Trusted partners: 600 requests per minute per key (configurable via TRUSTED_RATE_LIMIT_MAX). Send the issued key in the X-API-Key header. Each key has its own bucket — partners do not share quota.
Requests sent with an X-API-Key header that does not match the server-side allowlist receive 401 Unauthorized with code: "INVALID_API_KEY".
Keys are issued out-of-band by the team. Contact us if you need elevated access.

Error Handling

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "requestId": "uuid"
}

Code	Description
`400`	Bad Request (missing/invalid parameters)
`401`	Unauthorized (invalid `X-API-Key`)
`404`	Not Found
`429`	Rate limit exceeded
`503`	Service unavailable (DB not connected)
`500`	Internal server error

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github		.github
docs		docs
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.npmrc		.npmrc
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
example.env		example.env
package.json		package.json
tsconfig.json		tsconfig.json
vault-entrypoint.sh		vault-entrypoint.sh

Navigation Menu

Uh oh!

Repository files navigation

Futarchy External API

Public API Documentation

CoinGecko Endpoints

GET `/api/tickers`

CoinMarketCap Endpoints

GET `/cmc/summary`

GET `/cmc/ticker`

GET `/cmc/assets`

DexScreener Adapter Endpoints

GET `/dexscreener/latest-block`

GET `/dexscreener/asset?id=:mintAddress`

GET `/dexscreener/pair?id=:daoAddress`

GET `/dexscreener/events?fromBlock=:slot&toBlock=:slot`

Market Data

GET `/api/market-data?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&tokens=TOKEN1,TOKEN2`

Supply Endpoints

GET `/api/supply/:mintAddress`

GET `/api/supply/:mintAddress/total`

GET `/api/supply/:mintAddress/circulating`

Health & Admin

Installation

Configuration

Environment Variables

Architecture

Data Pipeline

Sources (Dune fully removed)

DexScreener Pipeline

Rate Limiting

Error Handling

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Futarchy External API

Public API Documentation

CoinGecko Endpoints

GET /api/tickers

CoinMarketCap Endpoints

GET /cmc/summary

GET /cmc/ticker

GET /cmc/assets

DexScreener Adapter Endpoints

GET /dexscreener/latest-block

GET /dexscreener/asset?id=:mintAddress

GET /dexscreener/pair?id=:daoAddress

GET /dexscreener/events?fromBlock=:slot&toBlock=:slot

Market Data

GET /api/market-data?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&tokens=TOKEN1,TOKEN2

Supply Endpoints

GET /api/supply/:mintAddress

GET /api/supply/:mintAddress/total

GET /api/supply/:mintAddress/circulating

Health & Admin

Installation

Configuration

Environment Variables

Architecture

Data Pipeline

Sources (Dune fully removed)

DexScreener Pipeline

Rate Limiting

Error Handling

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

GET `/api/tickers`

GET `/cmc/summary`

GET `/cmc/ticker`

GET `/cmc/assets`

GET `/dexscreener/latest-block`

GET `/dexscreener/asset?id=:mintAddress`

GET `/dexscreener/pair?id=:daoAddress`

GET `/dexscreener/events?fromBlock=:slot&toBlock=:slot`

GET `/api/market-data?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&tokens=TOKEN1,TOKEN2`

GET `/api/supply/:mintAddress`

GET `/api/supply/:mintAddress/total`

GET `/api/supply/:mintAddress/circulating`