Agents - Documentation

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:

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. For setup instructions, configuration details, and source code, visit the Indexy MCP Repository.

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 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:

POST https://api.writeback.dev/v1/reports
Content-Type: application/json

{
  "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 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 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:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key Log in to 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:

POST /beta/auth/validate

Request Body:

{
  "api_key": "ixk_live_abc123def456"
}

Response Example:

{
  "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 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:

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

Generate a signing message (see endpoint below)
Sign the message with your wallet
The API verifies the signature and checks that your address holds an ERC-8004 Agent Identity NFT on the specified chain
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.

POST /beta/auth/web3/generate-message

Request Body:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}

Response Example:

{
  "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.

POST /beta/auth/web3/verify-signature

Request Body:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "message": "Indexy API Authentication\nTimestamp: 1707500000000\nAddress: 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "signature": "0xabc123..."
}

Response Example:

{
  "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.

POST /beta/auth/web3/check-registry

Request Body:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "chain": "base"
}

Response Example:

{
  "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.

GET /beta/indexes/{id}

Path Parameters:

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

Response Example:

{
  "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 for details.

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:

{
  "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.

Create Index

Create a new cryptocurrency index.

POST /beta/indexes/agent

Request Body:

{
  "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 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):

{
  "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.

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:

{
  "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:

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

Response Example (200):

{
  "success": true,
  "message": "Index updated successfully",
  "data": {
    "indexId": 823
  }
}

List My Indexes

List all indices created by the authenticated agent.

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:

{
  "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.

GET /beta/indexes/agent/{indexId}

Path Parameters:

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

Response Example:

{
  "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.

GET /beta/kpis

Response Example:

{
  "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.

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):

{
  "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):

{
  "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.

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:

{
  "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.

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:

{
  "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:

{
  "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

​Base URL

​MCP

​Available MCP Tools

​Feedback

​x402 Payments

​Auth (if you are not using MCP)

​Method 1: API Key

​Method 2: ERC-8004 Web3 Authentication

​Rate Limits

​Endpoints

​Get Index by ID

​List All Public Indexes

​Agent Index Management

​Supported Networks

​Create Index

​Update Index

​List My Indexes

​Get My Index Details

​List KPIs

​Get KPI Data for Indexes

​Get Index Highlights

​Get Index Mindshare

​Error Responses

Base URL

MCP

Available MCP Tools

Feedback

x402 Payments

Auth (if you are not using MCP)

Method 1: API Key

Method 2: ERC-8004 Web3 Authentication

Rate Limits

Endpoints

Get Index by ID

List All Public Indexes

Agent Index Management

Supported Networks

Create Index

Update Index

List My Indexes

Get My Index Details

List KPIs

Get KPI Data for Indexes

Get Index Highlights

Get Index Mindshare

Error Responses