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

# Claims and creator actions

> Prepare fee claims, vesting claims, announcements, and token metadata updates.

## Fee and vesting claims

`POST /claims/prepare` accepts 1 to 10 positions for one chain and caller:

```json theme={null}
{
  "chain_id": 8453,
  "caller": "0x1111111111111111111111111111111111111111",
  "claims": [
    {
      "kind": "fee",
      "recipient": "0x1111111111111111111111111111111111111111",
      "fee_escrow": "0x2222222222222222222222222222222222222222",
      "currency": "0x0000000000000000000000000000000000000000",
      "mode": "to_recipient"
    }
  ]
}
```

Mixed chains, mixed callers, and duplicate positions are rejected before RPC work.

Fee claim modes:

* `to_recipient` calls `FeeEscrow.claim(recipient, currency)` and always pays the recorded recipient
* `redirect` calls `FeeEscrow.claimTo(currency, destination)` and requires the caller to be the recorded recipient

The API verifies the escrow belongs to a registered historical suite and reads live `owed` state. It never lets one caller redirect another recipient's balance.

Creator, platform, and valid referrer balances use this same fee-claim flow. A referrer does not need a separate claim endpoint: use the referrer's address as `recipient`, then either pay that address directly or let that same wallet authorize a redirect.

Vesting claims verify the historical vault and live `claimable(token, beneficiary)` amount. Claims pay according to the vault contract.

Every returned claim transaction is simulated independently. `review.claims` records the exact live claimable amount and linked step ID. The steps are independent, not atomic, and each receives Base builder attribution when applicable.

## Creator announcements

```http theme={null}
POST /tokens/{chain_id}/{token_address}/announcements/prepare
```

The API resolves the token's historical AnnouncementRegistry and verifies `creatorOf(token)` on-chain before building `post`.

Descriptions must be non-empty and are limited to 1000 UTF-8 bytes. The URI is optional; non-empty values use `https://`, `ipfs://`, or `ar://`.

## Token metadata

```http theme={null}
POST /tokens/{chain_id}/{token_address}/metadata/prepare
```

Supported operations:

* `update_name`
* `update_symbol`
* `update_profile`, which pins a new metadata document
* `update_extra_metadata`

`update_profile` is a partial update. Omitted description and link fields preserve their current values; an explicit empty string or `null` clears a link. Omitting both image fields preserves the current effective image. `image_uri` must be a non-empty `ipfs://` URI; use it to select an existing IPFS image, or supply `image_base64` and `image_type` together to upload a replacement.

Each profile update creates one metadata JSON object, plus one image object only when new image bytes are supplied. Name, symbol, and extra-metadata operations do not upload to IPFS.

Profile descriptions are limited to 2000 UTF-8 bytes. A replacement image follows the same MIME validation and 2 MB decoded-size limit as launch creation. Extra-metadata keys are 1 to 64 characters and values are at most 512 characters.

The API verifies the caller has the token's metadata authority: `METADATA_ROLE` on Base B20 tokens or the matching metadata authority on ERC-20 launches. It does not expose mint, burn, pause, operator, rebase, ownership, or governance operations.

The API selects the correct B20 or ERC-20 token interface for the launch's chain and simulates the requested operation. Unsupported historical suites fail with `unsupported_operation` instead of guessing. A Base B20 name update returns an `eip712_domain_changes` warning because the token's EIP-712 domain follows its name.

Every creator-action response includes RFC3339 preparation and expiry times, the observed chain block, a normalized operation review, and simulation state. `update_profile` requires `Idempotency-Key`; an expired replay returns `409 stale_plan` and must be prepared with a new key. It also returns `409 stale_plan` when the live contract URI is newer than the indexed profile, so the API never builds an update from stale metadata. Wait for indexing, then prepare again.