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

# API Overview

> Overview of the Futarchy CoinGecko-compatible DEX API

## What is This API?

The Futarchy CoinGecko DEX API is a CoinGecko-compatible API that automatically discovers and aggregates all DAOs from the Futarchy protocol, providing real-time pricing and trading information.

<Info>
  This API is fully compatible with CoinGecko's DEX API specification, making it easy to integrate with price aggregators and trading platforms.
</Info>

## Base URL

```
https://market-api.metadao.fi
```

All API requests should be made to this base URL.

## Available Endpoints

<CardGroup cols={2}>
  <Card title="GET /" icon="home" href="/api-reference/overview#root-endpoint">
    API information and available endpoints
  </Card>

  <Card title="GET /api/tickers" icon="chart-line" href="/api-reference/tickers">
    All DAO tickers with pricing and volume
  </Card>

  <Card title="GET /api/supply/:mint" icon="coins" href="/api-reference/supply">
    Token supply breakdown with allocation details
  </Card>

  <Card title="GET /api/volume/aggregate" icon="chart-bar" href="/api-reference/volume-aggregate">
    Aggregate volume with daily breakdown
  </Card>

  <Card title="GET /health" icon="heart" href="/api-reference/overview#health-endpoint">
    Health check endpoint
  </Card>
</CardGroup>

### Supply Endpoints

| Endpoint                                   | Description                                                    |
| ------------------------------------------ | -------------------------------------------------------------- |
| `GET /api/supply/:mintAddress`             | Returns complete supply breakdown with allocation details      |
| `GET /api/supply/:mintAddress/total`       | Returns total supply only                                      |
| `GET /api/supply/:mintAddress/circulating` | Returns circulating supply (excludes team performance package) |

### Volume Endpoints

| Endpoint                    | Description                                                                   |
| --------------------------- | ----------------------------------------------------------------------------- |
| `GET /api/volume/aggregate` | Returns aggregate volume with daily breakdown for all DAO tokens since launch |

## Root Endpoint

**Endpoint:** `GET /`

Returns API information and available endpoints.

**Response:**

```json theme={null}
{
  "name": "Futarchy AMM - CoinGecko API",
  "version": "1.0.0",
  "documentation": "https://docs.coingecko.com/reference/exchanges-list",
  "endpoints": {
    "tickers": "/api/tickers - Returns all DAO tickers with pricing and volume",
    "supply": "/api/supply/:mintAddress - Returns complete supply breakdown with allocation details",
    "supply_total": "/api/supply/:mintAddress/total - Returns total supply only",
    "supply_circulating": "/api/supply/:mintAddress/circulating - Returns circulating supply (excludes team performance package)",
    "volume_aggregate": "/api/volume/aggregate - Returns aggregate volume with daily breakdown for all DAO tokens since launch",
    "health": "/health"
  },
  "dex": {
    "fork_type": "Uniswap V1",
    "factory_address": "FUTARELBfJfQ8RDGhg1wdhddq1odMAJUePHFuBYfUxKq",
    "router_address": "FUTARELBfJfQ8RDGhg1wdhddq1odMAJUePHFuBYfUxKq"
  },
  "supplyBreakdown": {
    "description": "For launchpad tokens, supply is broken down into:",
    "circulatingSupply": "Total supply minus team performance package (liquidity IS circulating)",
    "teamPerformancePackage": "Locked tokens allocated to the team (price-based unlock) - NOT circulating",
    "futarchyAmmLiquidity": "Tokens in the internal FutarchyAMM for spot trading - IS circulating",
    "meteoraLpLiquidity": "Tokens in the external Meteora DAMM pool (POL) - IS circulating"
  },
  "note": "This API automatically discovers and aggregates all DAOs from the Futarchy protocol."
}
```

**Example Request:**

```bash theme={null}
curl https://market-api.metadao.fi/
```

## Health Endpoint

**Endpoint:** `GET /health`

Health check endpoint for monitoring API status.

**Response:**

```json theme={null}
{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "uptime": 3600.5
}
```

**Response Fields:**

<ResponseField name="status" type="string" required>
  Health status of the API. Always `"healthy"` when the endpoint responds successfully.
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  Current server timestamp in ISO 8601 format.
</ResponseField>

<ResponseField name="uptime" type="number" required>
  Server uptime in seconds.
</ResponseField>

**Example Request:**

```bash theme={null}
curl https://market-api.metadao.fi/health
```

<Tip>
  Use this endpoint for automated health monitoring. Set up checks every 1-5 minutes to detect issues early.
</Tip>

## Key Features

<AccordionGroup>
  <Accordion icon="magnifying-glass" title="Automatic DAO Discovery">
    The API automatically discovers all DAOs from the Futarchy protocol without manual configuration. No need to maintain a list of DAOs - they're discovered dynamically from the blockchain.
  </Accordion>

  <Accordion icon="coins" title="Real-Time Pricing">
    Prices are calculated from spot pool reserves in real-time, accounting for token decimal differences to ensure accuracy.
  </Accordion>

  <Accordion icon="chart-bar" title="Volume Tracking">
    Trading volumes are calculated from accumulated protocol fees, providing accurate volume metrics that reflect actual trading activity.
  </Accordion>

  <Accordion icon="droplet" title="Liquidity Metrics">
    Comprehensive liquidity information for all pools, calculated in USD for easy comparison.
  </Accordion>

  <Accordion icon="bolt" title="High Performance">
    Built with Bun for exceptional performance, featuring intelligent caching (10s for tickers, 100s for metadata) and rate limiting.
  </Accordion>

  <Accordion icon="shield" title="CoinGecko Compatible">
    Fully compatible with CoinGecko's DEX API specification, making integration seamless with existing tools and platforms.
  </Accordion>
</AccordionGroup>

## Rate Limiting

The API implements rate limiting to ensure fair usage:

* **60 requests per minute** per IP address
* Returns `429 Too Many Requests` when limit is exceeded
* Rate limits reset at the start of each minute window

## Caching

The API uses intelligent caching to balance freshness with performance:

* **Tickers**: 10 seconds TTL
* **Token Metadata**: 100 seconds TTL (longer cache for static data)

## Data Sources

All data comes from on-chain sources:

1. **Solana Blockchain** - Pool reserves, DAO accounts, protocol fees
2. **Metaplex Token Metadata** - Token symbols, names, and metadata
3. **Spot Pools Only** - Prices calculated from spot pools, not conditional markets

<Warning>
  Prices are only calculated from spot pools, not conditional/futarchy pools, to ensure spot market accuracy.
</Warning>

## Response Format

All endpoints return JSON responses. Error responses follow a consistent format:

```json theme={null}
{
  "error": "Error message describing what went wrong"
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Tickers Endpoint" icon="code" href="/api-reference/tickers">
    Learn about the tickers API endpoint
  </Card>

  <Card title="Supply Endpoint" icon="coins" href="/api-reference/supply">
    Get token supply information
  </Card>

  <Card title="Pricing Methodology" icon="calculator" href="/concepts/pricing-methodology">
    Understand how prices are calculated
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Get started with the API
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Configure your API instance
  </Card>

  <Card title="Error Handling" icon="exclamation-triangle" href="/advanced/error-handling">
    Learn how to handle API errors
  </Card>
</CardGroup>