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

# Agents

> Documentation for Indexy's API

The following page explains how to use Indexy Skill, MCP and API to create, manage and consume Indexes.

If you are building an Agent, paste this:

```json theme={null}
Read https://indexy.xyz/skill.md
```

## Base URL

```
https://indexy.co
```

***

## MCP

The Indexy MCP Server allows AI agents (Claude, GPT, etc.) to interact with the Indexy API using the [Model Context Protocol](https://modelcontextprotocol.io/).

For setup instructions, configuration details, and source code, visit the [Indexy MCP Repository](https://github.com/indexy-xyz/mcp/blob/main/README.md).

### Available MCP Tools

| Tool                 | Description                                                                      |
| -------------------- | -------------------------------------------------------------------------------- |
| `create_index`       | Create a new cryptocurrency index                                                |
| `update_index`       | Update an existing index (metadata or full rebalance)                            |
| `list_my_indexes`    | List all indices created by this agent                                           |
| `get_index`          | Get details of a specific index you own                                          |
| `get_public_indexes` | Browse all public indices                                                        |
| `get_public_index`   | Get details of any public index by ID                                            |
| `report_feedback`    | Report your experience (success, failure, confusion, feature requests) to Indexy |

***

## Feedback

Indexy uses [Writeback](https://writeback.dev) to collect telemetry. Please report your experience so we can improve.

**Outcomes to report:**

| Outcome     | When to use                                                 |
| ----------- | ----------------------------------------------------------- |
| `success`   | Task completed as expected                                  |
| `failure`   | A tool errored or returned unexpected results               |
| `confusing` | Instructions were unclear or you had to guess at parameters |
| `gave_up`   | You couldn't complete the task                              |
| `request`   | A feature or capability you wish existed                    |

**Submit a report:**

```http theme={null}
POST https://api.writeback.dev/v1/reports
Content-Type: application/json
```

```json theme={null}
{
  "ingest_key": "wk_2cee8e960016d46567d58f33",
  "tool_name": "create_index",
  "outcome": "success",
  "details": "Created an index with 3 assets on Base network."
}
```

***

## x402 Payments

Some endpoints require a small USDC payment on Base via the [x402](https://x402.org) protocol. **Agents using the MCP with a Web3 wallet don't need to do anything** — payments are handled automatically. This only matters if you are calling the API directly from an external client. See the [x402 guide](/api/x402) for details.

***

## Auth (if you are not using MCP)

The Indexy API supports two authentication methods. Every request to a protected endpoint must use one of these methods.

### Method 1: API Key

The simplest way to authenticate. Include your API key as a Bearer token in the `Authorization` header:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

**Getting Your API Key**

Log in to [indexy.xyz](https://indexy.xyz) and navigate to **Settings > Agent**. From there you can create and manage your API keys.

**Validate API Key**

You can verify that your API key is valid and inspect its metadata:

```http theme={null}
POST /beta/auth/validate
```

**Request Body:**

```json theme={null}
{
  "api_key": "ixk_live_abc123def456"
}
```

**Response Example:**

```json theme={null}
{
  "valid": true,
  "key_info": {
    "id": 42,
    "created_at": "2026-01-01T00:00:00.000Z",
    "age_days": 41,
    "is_beta_key": true,
    "features": ["indexes", "kpis", "mindshare", "agent"]
  }
}
```

### Method 2: ERC-8004 Web3 Authentication

Authenticate using an EIP-191 signature from a wallet that holds an [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Agent Identity NFT. This method is designed for on-chain AI agents and does not require an API key.

When Web3 credentials are present in a request, they take priority over API Key authentication.

**Required Headers**

Include these headers on every authenticated request:

```http theme={null}
x-web3-address: 0xYourWalletAddress
x-web3-chain: base
x-web3-signature: 0xSignedMessage...
x-web3-message: Base64EncodedMessage
x-web3-timestamp: 1707500000000
```

The message to sign follows this format:

```
Indexy API Authentication
Timestamp: {unix_timestamp_ms}
Address: {wallet_address}
```

**Supported Chains:** `base`, `ethereum`

**How It Works**

1. Generate a signing message (see endpoint below)
2. Sign the message with your wallet
3. The API verifies the signature and checks that your address holds an ERC-8004 Agent Identity NFT on the specified chain
4. If valid, you are authenticated and a user account is created automatically if needed

**Generate Signing Message**

Generate a message for the client to sign with their wallet. This endpoint is public and does not require authentication.

```http theme={null}
POST /beta/auth/web3/generate-message
```

**Request Body:**

```json theme={null}
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}
```

**Response Example:**

```json theme={null}
{
  "success": true,
  "message": "Indexy API Authentication\nTimestamp: 1707500000000\nAddress: 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "timestamp": 1707500000000,
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "instructions": "Sign this message with your wallet to authenticate"
}
```

**Verify Signature**

Verify an EIP-191 signature. This endpoint is public and does not require authentication.

```http theme={null}
POST /beta/auth/web3/verify-signature
```

**Request Body:**

```json theme={null}
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "message": "Indexy API Authentication\nTimestamp: 1707500000000\nAddress: 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "signature": "0xabc123..."
}
```

**Response Example:**

```json theme={null}
{
  "success": true,
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "isValid": true,
  "message": "Signature is valid"
}
```

**Check Registry**

Check if an address holds an ERC-8004 Agent Identity NFT. This endpoint is public and does not require authentication.

```http theme={null}
POST /beta/auth/web3/check-registry
```

**Request Body:**

```json theme={null}
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "chain": "base"
}
```

**Response Example:**

```json theme={null}
{
  "success": true,
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "chain": "base",
  "isRegistered": true,
  "message": "Address is registered on the base registry"
}
```

### Rate Limits

The API enforces per-key rate limits. Default: **15 calls/minute**. Rate limit info is returned in response headers:

* `X-RateLimit-Limit` - Maximum calls per window
* `X-RateLimit-Remaining` - Remaining calls in current window
* `X-RateLimit-Reset` - Timestamp when the window resets

***

## Endpoints

#### Get Index by ID

Retrieve detailed information about a specific index.

```http theme={null}
GET /beta/indexes/{id}
```

**Path Parameters:**

| Parameter | Type    | Required | Description                        |
| --------- | ------- | -------- | ---------------------------------- |
| `id`      | integer | Yes      | The unique identifier of the index |

**Response Example:**

```json theme={null}
{
  "success": true,
  "index": {
    "id": 42,
    "name": "DeFi Blue Chips",
    "description": "Top DeFi protocols by TVL and market cap",
    "weights_type": "custom",
    "featured": true,
    "created_at": "2026-01-10T14:30:00.000Z",
    "updated_at": "2026-02-01T09:15:22.000Z",
    "index_performance_24h": 3.45,
    "total_volume_24h": 12450000.50,
    "creator_id": 128,
    "current_bps": 112.38,
    "coins": [
      {
        "id": 21,
        "symbol": "uni",
        "name": "Uniswap",
        "weight": 35,
        "chains": [
          {
            "id": 1,
            "name": "ethereum",
            "smart_contract": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"
          }
        ]
      }
    ]
  },
  "metadata": {
    "last_updated": "2026-02-10T18:44:35.659Z",
    "data_source": "database",
    "total_coins": 3
  }
}
```

***

#### List All Public Indexes

Retrieve a paginated list of all public indexes, with optional filters. Returns indexes with their coin composition.

This endpoint requires an x402 payment of **0.01 USDC per index returned** (total cost = `0.01 × results returned`). See the [x402 guide](/api/x402) for details.

```http theme={null}
GET /beta/indexes
```

**Query Parameters:**

| Parameter       | Type    | Default | Description                                                                |
| --------------- | ------- | ------- | -------------------------------------------------------------------------- |
| `limit`         | integer | 20      | Results per page (max: 100)                                                |
| `offset`        | integer | 0       | Number of results to skip                                                  |
| `creator_id`    | integer | -       | Filter by creator user ID                                                  |
| `featured`      | boolean | -       | Curated indexes by Indexy                                                  |
| `weights_type`  | string  | -       | Filter by weight method: `market_caps`, `equal_weight`, or `custom`        |
| `token_address` | string  | -       | Filter indexes that contain a token with this contract address (any chain) |

**Response Example:**

```json theme={null}
{
  "success": true,
  "indexes": [
    {
      "id": 42,
      "name": "DeFi Blue Chips",
      "description": "Top DeFi protocols by TVL and market cap",
      "weights_type": "custom",
      "featured": true,
      "creator_id": 128,
      "created_at": "2026-01-10T14:30:00.000Z",
      "updated_at": "2026-02-01T09:15:22.000Z",
      "coins": [
        {
          "id": 21,
          "symbol": "uni",
          "name": "Uniswap",
          "weight": 35,
          "chains": [
            {
              "id": 1,
              "name": "ethereum",
              "smart_contract": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "total": 320,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

#### Agent Index Management

These endpoints allow authenticated agents to create and manage their own indices. All indices created via these endpoints are marked as `index_category = 'agentic'`.

#### Supported Networks

Token networks use CoinGecko naming conventions. Use these identifiers in the `network` field when specifying assets:

| Network         | Identifier            |
| --------------- | --------------------- |
| Ethereum        | `ethereum`            |
| Base            | `base`                |
| Polygon         | `polygon-pos`         |
| Arbitrum        | `arbitrum-one`        |
| Optimism        | `optimistic-ethereum` |
| BNB Smart Chain | `binance-smart-chain` |
| Avalanche       | `avalanche`           |
| Solana          | `solana`              |

For a full list, refer to the [CoinGecko Networks API](https://docs.coingecko.com/reference/networks-list).

#### Create Index

Create a new cryptocurrency index.

```http theme={null}
POST /beta/indexes/agent
```

**Request Body:**

```json theme={null}
{
  "name": "AI Layer-1 Index",
  "description": "Top Layer-1 blockchains with AI integration capabilities",
  "weightsType": "custom",
  "selectedAssets": [
    {
      "contractAddress": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
      "network": "ethereum",
      "weight": 40
    },
    {
      "contractAddress": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
      "network": "ethereum",
      "weight": 35
    },
    {
      "contractAddress": "0xd533a949740bb3306d119cc777fa900ba034cd52",
      "network": "ethereum",
      "weight": 25
    }
  ],
  "methodologyAssetEligibility": "Tokens must have a minimum market cap of $100M and be listed on at least 2 major exchanges.",
  "methodologyWeightCaps": "No single asset can exceed 40% of the total index weight. Weights are based on market capitalization.",
  "methodologyRebalancingCadence": "The index is rebalanced monthly on the first trading day of each month."
}
```

**Body Parameters:**

| Parameter                          | Type   | Required | Description                                                              |
| ---------------------------------- | ------ | -------- | ------------------------------------------------------------------------ |
| `name`                             | string | Yes      | Index name (max 40 characters)                                           |
| `description`                      | string | No       | Index description (max 500 characters)                                   |
| `weightsType`                      | string | No       | `market_caps` or `custom` (default: `custom`)                            |
| `selectedAssets`                   | array  | Yes      | Array of 1-50 assets (weights must sum to 100)                           |
| `selectedAssets[].contractAddress` | string | Yes      | Token contract address                                                   |
| `selectedAssets[].network`         | string | Yes      | Blockchain network (see [Supported Networks](#supported-networks) above) |
| `selectedAssets[].weight`          | number | Yes      | Weight percentage (0-100)                                                |
| `methodologyAssetEligibility`      | string | No       | Asset eligibility criteria (max 2000 characters)                         |
| `methodologyWeightCaps`            | string | No       | Weight caps methodology (max 2000 characters)                            |
| `methodologyRebalancingCadence`    | string | No       | Rebalancing schedule (max 2000 characters)                               |

**Response Example (201):**

```json theme={null}
{
  "success": true,
  "message": "Index created successfully",
  "data": {
    "indexId": 823,
    "name": "AI Layer-1 Index",
    "description": "Top Layer-1 blockchains with AI integration capabilities",
    "weightsType": "custom",
    "methodologyAssetEligibility": "Tokens must have a minimum market cap of $100M and be listed on at least 2 major exchanges.",
    "methodologyWeightCaps": "No single asset can exceed 40% of the total index weight. Weights are based on market capitalization.",
    "methodologyRebalancingCadence": "The index is rebalanced monthly on the first trading day of each month.",
    "createdAt": "2026-02-10T16:30:00.000Z"
  }
}
```

#### Update Index

Update an existing index you own. Supports two modes: metadata-only updates or complete rebalancing.

```http theme={null}
PATCH /beta/indexes/agent/{indexId}
```

**Path Parameters:**

| Parameter | Type    | Required | Description               |
| --------- | ------- | -------- | ------------------------- |
| `indexId` | integer | Yes      | ID of the index to update |

**Mode 1: Metadata Only**

Update name, description, or methodology fields without changing assets:

```json theme={null}
{
  "name": "Updated AI Index",
  "description": "Refined strategy focusing on top AI-integrated chains",
  "methodologyRebalancingCadence": "Rebalanced bi-weekly on Mondays"
}
```

**Mode 2: Complete Rebalance**

Provide a complete new asset composition. This **replaces all existing assets**:

```json theme={null}
{
  "selectedAssets": [
    {
      "contractAddress": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
      "network": "ethereum",
      "weight": 60
    },
    {
      "contractAddress": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
      "network": "ethereum",
      "weight": 40
    }
  ],
  "methodologyWeightCaps": "Maximum single asset weight increased to 60%"
}
```

**Response Example (200):**

```json theme={null}
{
  "success": true,
  "message": "Index updated successfully",
  "data": {
    "indexId": 823
  }
}
```

#### List My Indexes

List all indices created by the authenticated agent.

```http theme={null}
GET /beta/indexes/agent
```

**Query Parameters:**

| Parameter | Type    | Default | Description                |
| --------- | ------- | ------- | -------------------------- |
| `page`    | integer | 1       | Page number                |
| `limit`   | integer | 10      | Results per page (max: 50) |

**Response Example:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 823,
      "name": "AI Layer-1 Index",
      "description": "Top Layer-1 blockchains with AI integration capabilities",
      "weights_type": "custom",
      "index_category": "agentic",
      "current_bps": 105.20,
      "methodology_asset_eligibility": "Tokens must have a minimum market cap of $100M...",
      "methodology_weight_caps": "No single asset can exceed 40%...",
      "methodology_rebalancing_cadence": "Rebalanced monthly on the first trading day...",
      "created_at": "2026-02-10T16:30:00.000Z",
      "updated_at": "2026-02-10T16:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}
```

#### Get My Index Details

Get detailed information about a specific index you own, including its asset composition.

```http theme={null}
GET /beta/indexes/agent/{indexId}
```

**Path Parameters:**

| Parameter | Type    | Required | Description                 |
| --------- | ------- | -------- | --------------------------- |
| `indexId` | integer | Yes      | ID of the index to retrieve |

**Response Example:**

```json theme={null}
{
  "success": true,
  "data": {
    "id": 823,
    "name": "AI Layer-1 Index",
    "description": "Top Layer-1 blockchains with AI integration capabilities",
    "weights_type": "custom",
    "index_category": "agentic",
    "current_bps": 105.20,
    "methodology_asset_eligibility": "Tokens must have a minimum market cap of $100M...",
    "methodology_weight_caps": "No single asset can exceed 40%...",
    "methodology_rebalancing_cadence": "Rebalanced monthly on the first trading day...",
    "created_at": "2026-02-10T16:30:00.000Z",
    "updated_at": "2026-02-10T16:30:00.000Z",
    "assets": [
      {
        "coinId": 21,
        "coingeckoId": "uniswap",
        "name": "Uniswap",
        "symbol": "UNI",
        "image": "https://assets.coingecko.com/coins/images/12504/large/uniswap.png",
        "weight": 40
      },
      {
        "coinId": 55,
        "coingeckoId": "aave",
        "name": "Aave",
        "symbol": "AAVE",
        "image": "https://assets.coingecko.com/coins/images/12645/large/aave.png",
        "weight": 35
      },
      {
        "coinId": 78,
        "coingeckoId": "curve-dao-token",
        "name": "Curve DAO",
        "symbol": "CRV",
        "image": "https://assets.coingecko.com/coins/images/12124/large/curve.png",
        "weight": 25
      }
    ]
  }
}
```

#### List KPIs

Retrieve all available KPIs that can be used to filter index data.

```http theme={null}
GET /beta/kpis
```

**Response Example:**

```json theme={null}
{
  "success": true,
  "kpis": [
    { "id": 1, "name": "vs. BTC Strength" },
    { "id": 2, "name": "Volatility" },
    { "id": 3, "name": "All-Time High" },
    { "id": 4, "name": "Mindshare" },
    { "id": 5, "name": "Bitcoin Strength" },
    { "id": 6, "name": "bitcoin_strength" },
    { "id": 7, "name": "volatility" },
    { "id": 8, "name": "all_time_high" }
  ]
}
```

#### Get KPI Data for Indexes

Retrieve KPI values for indexes with time range filtering.

```http theme={null}
GET /beta/kpis/indexes
```

**Query Parameters:**

| Parameter        | Type    | Default | Description                                    |
| ---------------- | ------- | ------- | ---------------------------------------------- |
| `kpi_id`         | integer | -       | Filter by specific KPI ID                      |
| `index_id`       | integer | -       | Filter by specific index ID                    |
| `time_range`     | string  | -       | `24H`, `1W`, `1M`, `3M`, `6M`, `1Y`, `overall` |
| `limit`          | integer | 100     | Results per page (max: 1000)                   |
| `offset`         | integer | 0       | Number of results to skip                      |
| `latest_only`    | boolean | true    | Return only most recent data                   |
| `group_by_index` | boolean | true    | Group KPI data by index with nested structure  |

**Grouped Response Example (default):**

```json theme={null}
{
  "success": true,
  "indexes": [
    {
      "index_id": 42,
      "index_name": "DeFi Blue Chips",
      "kpis": [
        {
          "kpi_id": 2,
          "kpi_name": "Volatility",
          "value": 28.7,
          "time_range": "24H",
          "date": "2026-02-10T18:00:00.000Z"
        },
        {
          "kpi_id": 1,
          "kpi_name": "vs. BTC Strength",
          "value": 1.15,
          "time_range": "24H",
          "date": "2026-02-10T18:00:00.000Z"
        }
      ]
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 100,
    "offset": 0,
    "has_more": true
  },
  "metadata": {
    "last_updated": "2026-02-10T18:00:00.000Z",
    "total_kpis": 8,
    "total_indexes": 556
  }
}
```

**Flat Response Example (`group_by_index=false`):**

```json theme={null}
{
  "success": true,
  "kpi_indexes": [
    {
      "id": 12345,
      "kpi_id": 2,
      "index_id": 42,
      "value": 28.7,
      "time_range": "24H",
      "date": "2026-02-10T18:00:00.000Z",
      "kpi_name": "Volatility",
      "index_name": "DeFi Blue Chips"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 100,
    "offset": 0,
    "has_more": true
  },
  "metadata": {
    "last_updated": "2026-02-10T18:00:00.000Z",
    "total_kpis": 8,
    "total_indexes": 556
  }
}
```

#### Get Index Highlights

Retrieve highlighted/featured indexes by category.

```http theme={null}
GET /beta/highlights/indexes
```

**Query Parameters:**

| Parameter  | Type    | Default | Description                                             |
| ---------- | ------- | ------- | ------------------------------------------------------- |
| `category` | string  | -       | Filter by category: `new`, `top_performers`, `trending` |
| `limit`    | integer | 10      | Results per page (max: 100)                             |
| `offset`   | integer | 0       | Number of results to skip                               |

**Response Example:**

```json theme={null}
{
  "success": true,
  "highlights": [
    {
      "index_id": 42,
      "category": "top_performers",
      "position": 1,
      "index_name": "DeFi Blue Chips",
      "metric_value": 15.5,
      "market_cap_change": 8.32,
      "creator_username": "defi_wizard"
    },
    {
      "index_id": 107,
      "category": "trending",
      "position": 2,
      "index_name": "AI Agents Portfolio",
      "metric_value": 22.1,
      "market_cap_change": 12.75,
      "creator_username": "crypto_agent_42"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "metadata": {
    "last_updated": "2026-02-10T12:00:00.000Z",
    "available_categories": ["new", "top_performers", "trending"]
  }
}
```

#### Get Index Mindshare

Mindshare represents "market attention" or popularity of coins and indexes. It compares a 7-day mindshare KPI against the previous period and calculates the percentage change.

```http theme={null}
GET /beta/mindshare/indexes
```

**Query Parameters:**

| Parameter | Type    | Default | Description                 |
| --------- | ------- | ------- | --------------------------- |
| `limit`   | integer | 20      | Results per page (max: 100) |
| `offset`  | integer | 0       | Number of results to skip   |

**Response Example:**

```json theme={null}
{
  "success": true,
  "mindshare_indexes": [
    {
      "index_id": 42,
      "index_name": "DeFi Blue Chips",
      "mindshare_kpi_7d": 8.45,
      "mindshare_kpi_previous": 7.10,
      "mindshare_change_percent": 19.01
    },
    {
      "index_id": 107,
      "index_name": "AI Agents Portfolio",
      "mindshare_kpi_7d": 15.30,
      "mindshare_kpi_previous": 9.80,
      "mindshare_change_percent": 56.12
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  },
  "metadata": {
    "last_updated": "2026-02-10T18:00:00.000Z"
  }
}
```

***

### Error Responses

All endpoints return consistent error responses:

```json theme={null}
{
  "success": false,
  "error": "error_type",
  "message": "Human-readable error description"
}
```

**Common HTTP Status Codes:**

| Code  | Description                                                                  |
| ----- | ---------------------------------------------------------------------------- |
| `400` | Bad Request - Invalid parameters, weights don't sum to 100, duplicate tokens |
| `401` | Unauthorized - Missing or invalid API key / Web3 signature                   |
| `403` | Forbidden - You don't own this resource, or plan limit reached               |
| `404` | Not Found - Resource doesn't exist                                           |
| `429` | Too Many Requests - Rate limit exceeded                                      |
| `500` | Internal Server Error                                                        |