# Character Markets API

Use the Charms Character Markets API to list character markets launched through Charms, or to resolve a Base contract address to its official Charms character.

Characters are the center of Charms. When a creator launches a character, a market is generated around it. That market lets people participate in the character's economy and helps fund the character over time.

Under the hood, each character market is backed by a token on Base. The endpoint path uses `tokens`, but each item represents a character market in Charms.

No authentication is required. The API only returns metadata about characters, markets, token contracts, and creators.

For verification details, see [Market Proof](/markets/market-proof.md).

### Base URL

```
https://api.charms.ai/api
```

### List Character Markets

```bash
curl "https://api.charms.ai/api/tokens/charms?limit=50"
```

Returns character markets launched through Charms, newest first.

Query parameters:

* `limit`: number of character markets to return. Defaults to `50`; maximum `100`.
* `cursor`: pagination cursor returned as `pagination.nextCursor`.
* `launchedAfter`: optional ISO timestamp for polling newer launches.

Do not send `cursor` and `launchedAfter` in the same request.

### Resolve a Contract Address

```bash
curl "https://api.charms.ai/api/tokens/charms/0xc29832025e7652ef58d15f7fa3e232a2fdfaab07"
```

Checks whether a Base contract address belongs to an official Charms-launched character market.

If the address is recognized, the API returns the linked character, market data, token contract, and creator metadata. If it is not a Charms-launched character market, the API returns `404`.

### Response Shape

The list endpoint returns market objects inside `tokens`, plus pagination metadata.

The contract address endpoint returns the same market object directly.

```json
{
  "tokens": [
    {
      "contractAddress": "0xc29832025e7652ef58d15f7fa3e232a2fdfaab07",
      "chain": "base",
      "chainId": 8453,
      "name": "Zoe",
      "symbol": "ZOE",
      "decimals": 18,
      "launchedAt": "2026-04-30T18:02:11+00:00",
      "url": "https://charms.ai/character/zoe",
      "explorerUrl": "https://basescan.org/token/0xc29832025e7652ef58d15f7fa3e232a2fdfaab07",
      "priceUsd": 0.00000257,
      "marketCapUsd": 257081,
      "circulatingMarketCapUsd": 205664,
      "change24hPercent": -0.023631936746715435,
      "volume24hUsd": 21640,
      "holders": 566,
      "totalSupply": 100000000000,
      "slug": "zoe",
      "avatarUrl": "https://...",
      "videoUrl": "https://...",
      "isVerified": true,
      "totalChats": 17796,
      "creator": {
        "username": "charms",
        "isVerified": true,
        "xHandle": "charmsai",
        "xUrl": "https://x.com/charmsai",
        "profileUrl": "https://charms.ai/user/charms"
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "nextCursor": "eyJsYXVuY2hlZEF0IjoiLi4uIn0",
    "hasMore": true
  }
}
```

Fields may be `null` when the source data is not available.

### Rate Limits

The API is rate limited. If you exceed the limit, it returns `429 Too Many Requests` with rate limit headers.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.charms.ai/developers/public-markets-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.