Skip to main content

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

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:
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:
Its body contains actor and document directly; there is no operation field:
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.