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

The API uses separate preparation routes because fee and vesting positions have different contract inputs. Neither request needs a `kind` field.

### Trading-fee claims

`POST /claims/fees/prepare` accepts 1 to 10 fee positions returned by `GET /wallets/{address}/fee-claims`:

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

`recipient` is the wallet entitled to the fee balance. Use the position's `fee_escrow_address` as `fee_escrow` and `currency.address` as `currency`.

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 endpoint. For a referral balance, use the referrer's address as `recipient`, then either pay that address directly or let that same wallet authorize a redirect.

### Vesting claims

`POST /claims/vesting/prepare` accepts 1 to 10 positions returned by `GET /wallets/{address}/vesting`:

```json theme={null}
{
  "chain_id": 8453,
  "caller": "0x1111111111111111111111111111111111111111",
  "claims": [
    {
      "beneficiary": "0x1111111111111111111111111111111111111111",
      "token_address": "0x2222222222222222222222222222222222222222",
      "vault": "0x3333333333333333333333333333333333333333"
    }
  ]
}
```

`beneficiary` is the wallet entitled to and receiving the unlocked tokens, while `token_address` identifies the vested launch token. Use the position's `vault_address` as `vault`.

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

The wallet routes default to claimable positions and support cursor pagination. Each preparation batch uses one chain and caller. Both routes reject duplicate positions and fields belonging to the other claim type before RPC work. Every returned 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. Claim preparation costs 3 weighted units per position, so a 10-position batch costs 30 units.

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

On-chain name, symbol, and extra-metadata updates use:

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

Supported operations:

* `update_name`
* `update_symbol`
* `update_extra_metadata`

These operations perform live authority checks and simulation but do not upload content to IPFS. They cost 3 units.

Description, image, and public-link updates use the dedicated idempotent metadata-document route:

```http theme={null}
POST /tokens/{chain_id}/{token_address}/metadata/document/prepare
Idempotency-Key: unique-request-key
```

Its body contains `actor` and `document` directly; there is no `operation` field:

```json theme={null}
{
  "actor": "0x1111111111111111111111111111111111111111",
  "document": {
    "description": "Updated token description",
    "website": "https://example.com",
    "x": "https://x.com/example",
    "telegram": "https://t.me/example",
    "image_uri": "ipfs://bafy..."
  }
}
```

Document preparation 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 document update creates one metadata JSON object, plus one image object only when new image bytes are supplied.

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. Metadata-document preparation 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 document, so the API never builds an update from stale metadata. Wait for indexing, then prepare again.

The earlier `/metadata/prepare` and `/metadata/profile/prepare` forms remain available during migration and return deprecation headers. New integrations should use the focused on-chain or document route.