o1.exchange 백서 전문

ently. `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. On Arc, use each returned claim position's exact currency address and raw amount. ERC-20 USDC claims have six decimals; native USDC amounts have 18. Sharing a wallet balance does not merge separate escrow claim positions. Submit the prepared claim unchanged; claiming does not require an additional USDC payment. ## Dividend actions Use `GET /wallets/{address}/dividends?chain_id=8453` to discover indexed positions. For supported fee-accrual tokens, `POST /claims/dividends/prepare` accepts 1 to 10 distinct token/holder positions with `operation: "claim"`: ```json theme={null} { "chain_id": 8453, "caller": "0x1111111111111111111111111111111111111111", "claims": [ { "token_address": "0x2222222222222222222222222222222222222201", "holder": "0x1111111111111111111111111111111111111111", "operation": "claim", "unwrap_native": true } ] } ``` Trading already assigns these rewards. The current Tax contracts have no separate distribution transaction. The request schema retains `distribute` and `distribute-and-claim` for compatibility, but the current implementation rejects both with `422 unsupported_operation` before preparing calldata. Use `claim`. The caller must be the wallet entitled to the rewards, including a smart wallet. It need not still hold the tokens. The recorded receiver remains the payout destination; changing `holder` cannot authorize a claim for someone else. `unwrap_native` is required. For a wrapped-native reward token, `true` requests native currency and `false` requests the wrapped token. The app defaults to the chain native currency (ETH, BNB, MON or OKB) for native pairs and preserves ERC-20 rewards. Monad WETH is distinct from WMON and remains WETH. On Arc, both unwrap preferences pay the fixed ERC-20 reward token: USDC uses six decimals and cirBTC uses eight. No wrapping or native payout conversion occurs. Other reward currencies are unchanged. Claims require no ERC-20 or Permit2 approval. Preparation verifies the registered clone, holder, receiver and current earnings, then simulates the exact withdrawal. A backing deficit alone does not prove that a particular claim will fail; available backing alone does not guarantee payment. Read the simulation result and confirm actual payment from the transaction receipt. Fee-accrual responses distinguish earned rewards from escrow funding. `pending_funding_raw` backs already-assigned rewards; it is not a pending distribution or the holder's payment. `available_reward_backing_raw`, `required_reward_backing_raw` and `backing_deficit_raw` describe contract backing. `withdrawable_before_raw` and `simulated_holder_paid` describe this claim before submission. Historical allocation fields must not be reinterpreted as funding. The API returns **independent transaction steps** (`review.atomic: false`). Each may succeed or fail separately. The app's dedicated cross-token helper is a different [atomic Claim all flow](/launchpad/integration/tax-tokens#dividends-and-batching). Never submit holder withdrawals through generic Multicall3. Use the chain's exact Tax deployment from the [support matrix](/launchpad/api/introduction#chain-and-product-support), and verify it appears in the deployed API configuration. Resolve each token by its originating suite and chain for discovery and preparation. Index-only historical Tax deployments are not public preparation targets; Arc Tax uses its own registered clone and fixed helper. For burn redemption, the ordinary fee endpoint can prepare `to_recipient` using the suite escrow, the dead address as recipient and the launched token as currency. It pays no caller reward and cannot redirect that entry. See [Token burns](/launchpad/tax/burns). ## Creator announcements ```http theme={null} POST /tokens/{chain_id}/{token_address}/announcements/prepare ``` The API resolves the exact contracts recorded for the token. For launches from any current factory it verifies `currentCreatorOf(token)` through the factory plus `isTokenRegistered(token)` through the registry, then builds `postAnnouncement`. Earlier launch contracts use their original `creatorOf` and `post` surface. 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. For launches from any current factory, the API verifies the caller's creator rights through the factory and prepares its typed metadata-forwarding function. Earlier Base B20 and Robinhood ERC-20 contracts use their original metadata-authority model. The API does not expose token minting, supply-burning, pause, operator, rebase, ownership or governance operations. Redeeming existing burn escrow credits is a separate fixed-recipient claim. The API selects the correct B20 or ERC-20 token interface for the launch's originating suite and simulates the requested operation. Unsupported earlier contracts 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. # Errors, rate limits, and retries Source: https://docs.o1.exchange/launchpad/api/errors-and-limits Handle problem responses, weighted quotas, cursors, idempotency, and safe retries. ## Problem responses Errors use `application/problem+json`: ```json theme={null} { "type": "https://docs.o1.exchange/launchpad/api/errors-and-limits#stale-plan", "title": "Transaction plan is stale", "status": 409, "code": "stale_plan", "detail": "The transaction plan expired. Prepare it again.", "action": "Prepare a new transaction plan before signing or broadcasting.", "instance": "urn:o1:request:req_...", "request_id": "req_..." } ``` `type` links to the exact code section on this page. `code` is the stable value for program logic, `detail` explains this occurrence, `action` gives the safe next step, and `request_id` identifies the request for support. Validation problems can also include `invalid_parameters`. Resource errors can include `resource`, `chain_id`, `token_address`, and `suggested_endpoint`. Balance errors can include `asset`, `actual_raw`, and `required_raw`. Raw RPC errors, stack traces, internal IDs, provider bodies, and secrets are never returned. Treat `detail` and `action` as human-readable text that may improve over time. Branch only on `status` and `code`. ## Problem code reference ### Request validation * `invalid_request` (`400` or `413`): the request, JSON transport, or body size is invalid. Correct the request using `detail`, then send it again. * `unknown_parameter` (`400`): one or more fields are not supported. Remove the fields listed in `invalid_parameters`. * `duplicate_parameter` (`400`): a query parameter was supplied more than once. Supply it once. * `incompatible_parameters` (`400`): individually valid parameters cannot be used together. Follow `invalid_parameters` and `suggested_endpoint` when present. * `invalid_parameter` (`400`): one or more fields have invalid values or formats. Correct the fields listed in `invalid_parameters`. * `missing_idempotency_key` (`400`): an operation that can create off-chain work needs `Idempotency-Key`. Send a new random UUID. * `invalid_idempotency_key` (`400`): the retry ID is empty or too long. Send 1 to 255 characters. ### Authentication and authorization * `missing_api_key` (`401`): `x-api-key` is absent. Send an active API key in that header. * `invalid_api_key` (`401`): the key is malformed, inactive, revoked, expired, or does not verify. Use an active key or create a replacement. * `origin_not_allowed` (`403`): the browser origin is not allowed by the key. Use an allowed origin or update the key's origin restrictions. * `insufficient_scope` (`403`): the key lacks the scope named in `detail`. Use a key with that scope. * `wallet_not_authorized` (`403`): the wallet does not own the required role, quote, claim, or resource. Use the authorized wallet. ### Resources and current state * `not_found` (`404`): the tracked resource or API operation does not exist. Verify the chain and identifier, use `suggested_endpoint` when present, and do not continuously retry an unchanged `404`. * `stale_plan` (`409`): a transaction plan expired or its chain configuration changed. Prepare a new plan before signing or broadcasting. * `stale_quote` (`409`): the quote expired or current execution state moved outside its reviewed limits. Request and review a fresh quote. * `salt_unavailable` (`409`): the prepared launch salt is already used. Prepare the launch again for a new salt and token address. * `invalid_permit` (`409`): Permit2 state changed or the signature no longer matches. Request a fresh quote, sign its current data, and prepare again. * `approval_not_confirmed` (`409`): the required token approval is not confirmed on-chain. Confirm it, then prepare again. * `announcement_id_conflict` (`409`): the generated announcement identifier is already used. Prepare again for a new identifier. * `cursor_filter_mismatch` (`409`): the cursor belongs to another route or filter set. Restart without a cursor and keep the same route and filters on later pages. * `cursor_stale` (`409`): the resource ordering changed after the cursor was issued. Restart from the first page. * `idempotency_in_progress` (`409`): an identical request is still running. Wait briefly, then retry the exact request with the same key. * `nothing_to_claim` (`409`): the requested position currently has no claimable value. Refresh the wallet's claim positions after state changes. ### Unsupported or non-executable requests * `unsupported_operation` (`422`): the resource, contract configuration, paired asset, or operation is not supported. Read `/config` and use a supported combination. * `unsupported_chain` (`422`): the chain is not supported. Use Base `8453`, Robinhood `4663`, Monad `143`, Arc `5042`, BSC `56` or X Layer `196`. * `idempotency_key_reused` (`422`): the retry ID was already used with different input. Generate a new UUID. * `invalid_amount` (`422`): the amount is invalid for the requested operation or current wallet state. Correct it using `detail`. * `invalid_referrer` (`422`): the referrer is reserved, duplicated, or otherwise ineligible. Remove it or use a separate eligible wallet. * `insufficient_balance` (`422`): the wallet cannot fund the requested operation. Fund at least `required_raw` of `asset`, then prepare again. * `quote_unavailable` (`422`): no safe executable quote exists for the token, side, amount, or current pool state. Correct the input or retry after market state changes. * `simulation_failed` (`422`): the unsigned transaction did not simulate successfully. Resolve the condition in `detail`, then prepare again. ### Limits and service failures * `rate_limit_exceeded` (`429`): the API key exceeded a weighted burst, minute, day, or month limit. Wait for `Retry-After`. * `quota_exceeded` (`429`): a key, wallet, token, creator, source, service, or concurrency safety ceiling was reached. Wait for `Retry-After` and reduce frequency or concurrency. * `internal_error` (`500`): an unexpected server fault occurred. Retry once; if it persists, contact support with `request_id`. * `upstream_error` (`502`): a required chain, metadata, indexer, holder, or internal origin dependency returned an invalid response. Retry with capped exponential backoff and jitter. * `temporarily_unavailable` (`503`): a required service or verified live state is unavailable. Retry with capped exponential backoff and jitter. * `upstream_timeout` (`504`): a required dependency timed out. Retry with capped exponential backoff and jitter. ## Weighted rate limits `GET /health` and browser preflight requests do not consume API-key units. Every other operation is authenticated and metered against the calling key. A successful preflight only confirms browser transport; the following API request must still pass API-key, scope, origin, validation, and rate-limit checks. Requests consume units: | Operation | Units | | - | -: | | configuration: `include=chains` only, or transaction status | 1 | | configuration: live crypto-paired contracts or paired assets | 5 | | configuration: live stock-paired or `market=all` contracts or paired assets | 20 | | token list, search, creator list, detail, or wallet summary | 2 | | token trades, wallet activity, fee claims, Dividend positions, announcement prepare, or on-chain metadata prepare | 3 | | fee or Dividend action preparation | 3 per position | | token announcements | 2 | | swap quote or prepare | 5 | | holder snapshot | 10 | | IPFS metadata-document prepare | 10 | | launch prepare | 20 | Configuration costs reflect whether a request needs live chain reads. Paginated reads scale with the requested page size: token lists, search, creator lists, and announcements use 2 units per 25 rows; trades, wallet activity, and fee claims use 3 units per 25 rows; holders use 10 units per 50 rows. Claim batches scale by position, so 10 prepared claims cost 30 units. For example, `GET /tokens?limit=100` costs 8 units and a 200-holder page costs 40 units. Initial plans: | Plan | Units/min | Burst/sec | Daily | Monthly | Max page | | - | -: | -: | -: | -: | -: | | Playground | 60 | 20 | 2,500 | 50,000 | 50 | | Developer | 300 | 20 | 25,000 | 500,000 | 100 | | Builder | 1,200 | 100 | 250,000 | 5,000,000 | 200 | | Partner | Custom | Custom | Custom | Custom | Custom | Additional safety ceilings apply before expensive work begins: * **Launch preparation:** protects the complete launch workflow, including live configuration reads, metadata uploads, `01` address mining, calldata construction, and simulation. One key can prepare up to 3 launches per minute and 100 per day. Within that key, the same creator is limited to 1 per minute and 25 per day; a different key cannot consume the counter. * **Metadata documents:** the IPFS document route allows up to 10 preparations per key each minute and 100 per day. Within that key, the same token is limited to 2 per minute and 25 per day. Name, symbol, and extra-metadata preparation does not use these pinning caps. * **Trading:** the same wallet can request up to 60 swap quotes and 30 swap preparations per minute across all keys. * **Claims:** one key can prepare up to 20 fee-claim batches per minute. The same chain and caller are limited to 10 batches per minute across all keys; each batch contains 1 to 10 independent positions. * **Creator actions:** within each key, the same creator or metadata actor is limited to 20 announcement or metadata preparations per minute. * **Holder protection:** holder snapshots allow 2 concurrent requests per key. Shared safeguards stop fresh-key cycling without changing ordinary use: * **Authentication:** uncached key-prefix lookups allow 60 requests per source each minute. Authorization results may be cached for up to 5 seconds for valid keys and 2 seconds for unknown keys. * **Live configuration:** 15 requests per source and 120 across the service each minute, with 10 in flight. * **Holder snapshots:** 60 requests per source and 300 across the service each minute, with 20 in flight. * **Launch workflow:** 6 requests per source each minute and 200 per day; 60 across the service each minute and 2,000 per day. * **Metadata-document pinning:** 20 requests per source each minute and 500 per day; 120 across the service each minute and 5,000 per day. These limits apply only to the document preparation route, which can upload content. * **All live transaction preparation:** 120 requests per source and 1,000 across the service each minute, with 50 preparations in flight. New keys use the Developer limits. Higher limits are reviewed per key, and Partner access uses a custom per-key policy. Responses include `RateLimit`, `RateLimit-Policy`, `X-RateLimit-*`, and `X-Request-Id`. A 429 includes `Retry-After`. Compatibility routes also expose `Deprecation` and `Link` headers. These headers do not change route behavior; follow the linked migration guide for the focused replacement. Limits apply across simultaneous requests. Higher limits, including Partner policies, are assigned per key. ## Tax-specific validation Invalid inclusive units, allocation totals, policy bounds, minimum holdings or incompatible tax formats reject before a launch is prepared. Read the returned policy instead of treating 1% to 10% as permanent. A disabled factory is unavailable for new creation; it does not turn an existing token into a different suite. Fee-accrual Tax tokens support claims of assigned rewards, not separate distribution operations. Index-only historical suites are not public transaction-preparation targets. A recorded entitlement may still be non-payable because of exclusion, missing backing or receiver failure. Withdrawals require the wallet entitled to the rewards; changing `holder` cannot grant authority. Use the problem detail to correct the re