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

# Create a Watchlist

> Create a watchlist of wallets, with your own id or one we generate, optionally with its first wallets. Free.

`POST /v1/wallet/watchlist` · **Free**

Creates a watchlist of wallets, optionally with its first wallets. Give it your own `id`, or omit it and we generate one (`wl_` + 16 hex characters). Creating an id you already have adds the wallets to it (`created: false`, status 200); a new list answers 201. Free: watchlist management costs 0 credits and stays open when your credits run out.

> [!NOTE]
>
> At most 1,000 wallets across all your watchlists and 1,000 watchlists per account (contact us to raise the wallet cap). A call that would go past a cap is refused whole (`429``RATE_LIMITED`, `details.limit``watchlistWallets` or `watchlists`, with `max` and `current`): nothing is written.

```bash cURL theme={null}
curl -X POST 'https://api.serialized.xyz/v1/wallet/watchlist' \
  -H 'Authorization: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"id":"app-holders","wallets":[{"address":"Hasda78TSaT9bjiPxDBvP4GpohFpP3TDTaJEcCYK5kyN","chain":"solana"},{"address":"0x95d955179a7cd45aeef394ed39f6a8d8b1bd1e09","chains":"evm"},{"address":"not-a-wallet","chain":"solana"}]}'
```

```json Response theme={null}
{
  "data": {
    "id": "app-holders",
    "created": true,
    "version": 4180,
    "wallets": 2,
    "added": 2,
    "alreadyIn": 0,
    "rejected": [
      {
        "index": 2,
        "error": {
          "code": "INVALID_PARAM",
          "message": "Invalid parameter \"wallets[2].address\": invalid Solana wallet address",
          "details": {
            "param": "wallets[2].address"
          }
        }
      }
    ]
  }
}
```


## OpenAPI

````yaml openapi.json POST /v1/wallet/watchlist
openapi: 3.1.0
info:
  title: Serialized Data API
  description: >-
    On-chain data for trading apps - tokens, candles, token filters. Built on
    our own indexers. 18 EVM chains + Solana, live.
  version: 0.1.0
servers:
  - url: https://demo.serialized.xyz
    description: 'Demo: no key needed, read endpoints, rate-limited per IP'
  - url: https://api.serialized.xyz
    description: 'Production: your API key in the Authorization header'
security:
  - apiKey: []
  - {}
paths:
  /v1/wallet/watchlist:
    post:
      summary: Create a Watchlist
      description: >-
        Creates a watchlist of wallets, optionally with its first wallets. Give
        it your own `id`, or omit it and we generate one (`wl_` + 16 hex
        characters). Creating an id you already have adds the wallets to it
        (`created: false`, status 200); a new list answers 201. Free: watchlist
        management costs 0 credits and stays open when your credits run out.
      operationId: watchlist-create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              properties:
                id:
                  description: >-
                    1 to 64 characters among `A-Z a-z 0-9 _ . : -`, not starting
                    with a dot. Omitted: we generate one.
                  type: string
                  example: app-holders
                  x-default: app-holders
                wallets:
                  description: >-
                    1 to 10,000 wallets per call: `{ "address": "…", "chain":
                    "…" }` (one chain: `solana` or `evm:<id>`) or `{ "address":
                    "…", "chains": "evm" }` (every EVM chain, counted as one
                    wallet). Same rules as the `wallet` and `chains` parameters
                    of the wallet streams. An address is on every EVM chain or
                    on named EVM chains, never both: an entry that would put it
                    on both is returned in `rejected` (`INVALID_PARAM`). An
                    invalid entry is returned in `rejected` with its index; the
                    others are applied.
                  type: array
                  items: {}
      responses:
        '200':
          description: Standard `{ data, meta }` envelope.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header
      description: Your raw API key (not needed on the demo server).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.