Skip to main content

Documentation Index

Fetch the complete documentation index at: https://blank.build/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Troubleshooting

A launch bundle can contain more than one transaction, so the wallet has to sign them as a group. If the SDK throws WALLET_SIGN_ALL_TRANSACTIONS_REQUIRED, switch to a wallet adapter that supports signAllTransactions, or wrap your existing one before calling blank.launch.create(). Same fix for WALLET_SIGN_TRANSACTION_REQUIRED on a single-transaction build — the adapter is missing signTransaction.
The SDK got back a build response with no transactions to sign. This is a bug-shaped state, not a wallet problem. Call blank.launch.create() again to rebuild. If it keeps happening, grab the X-Request-Id from the failing build response and report it.
Build payloads contain a recent blockhash and expire fast (~60 seconds). Build, sign, and submit in one go. If the user steps away mid-flow, just build again. Idempotency keys are independent — they live for 5 minutes and only deduplicate retries; they don’t extend the blockhash window.
The signed transaction message doesn’t match what the worker built. Almost always means the wallet rewrote fee payers, blockhash, compute-unit instructions, or address lookup tables before signing. Disable any “transaction enhancement” features in the wallet, or wrap the adapter so it signs the bytes verbatim. Then rebuild and sign again.
Keep metadataUri under 72 bytes. Use canonical ipfs://... or ar://... URIs — gateway URLs are rejected. The 72-byte cap applies even when the launch bundle uses two transactions.
The worker rejects gateway URLs (gateway.pinata.cloud, dweb.link, nftstorage.link, cloudflare-ipfs.com, arweave.net, etc.) because gateways can disappear, redirect, or rate-limit. Use the canonical ipfs://<cid>/... or ar://<txid> form.
The built transaction blew past the launch-payload size safety gate. The variable inputs are name, symbol, metadataUri, and creatorFeeSplit. Shorten the name, shorten the symbol, switch to a compact ipfs:// or ar:// URI, or reduce the number of fee-split entries.
Blank resolves metadata before it builds launch transactions. The metadata URI must return public JSON, and that JSON must include an image URI. Upload the image and metadata first, then poll a public gateway until the metadata returns HTTP 200 JSON with the expected image. Pass the canonical ipfs://... or ar://... URI to Blank, not the gateway URL, then rebuild.
The transaction is confirmed, but Blank has not finished activating the token row, staking state, and discovery data yet. Retry the status request. The SDK treats this as retryable and keeps polling until activation finishes or the launch payload expires.
The creator wallet you passed equals Blank’s own launch signer. Usually happens when an example wallet address gets copied into a bot config. Pass the bot/controller wallet you actually own, or omit creator so it defaults to the wallet that signs.
staking.shareBps must be an integer from 100 to 10_000. Send 2_000 for 20% of the creator’s fee share, or omit staking if the launch should start without a staking pool.
Splits use basis points (100 bps = 1%). Every launch’s creatorFeeSplit has to sum to exactly 10_000 across one to five unique wallets. A 7_000 / 3_000 split is 70% / 30%; 7_000 / 2_900 gets rejected by schema validation as LAUNCH_BUILD_INVALID_REQUEST.
Staking is already on, or it was already enabled on-chain and we just synced our database. Either way: you’re done, no signing needed.
Usually means staking isn’t enabled yet, or the on-chain pool isn’t there yet. For new tokens, prefer enabling staking in blank.launch.create({ staking: { shareBps } }); for existing tokens, call blank.staking.enable() and wait for that transaction to confirm before topping up.
Top-ups are distributed to stakers. There has to be at least one active staker who isn’t the controller before you can drop a bonus into the pool.
A zero response usually means no fees have accrued yet, the fee collector hasn’t been initialized, or the indexer hasn’t picked up the token. If only total_staking_earned is zero, check staking_enabled first — staking rewards only start accruing once blank.staking.enable() has been called and the pool is active. The fee endpoint is public, so this is never an auth problem.
Write routes need a valid secret key from a Blank account that has a username set. Send it as Authorization: Bearer sk_blank_... (or x-blank-api-key). API_KEY_INVALID also covers revoked, expired, or malformed keys — rotate in Settings → API Keys. If you don’t have a key yet, see Authentication.
The Blank account that owns the API key has no username set. Set a username on the account before creating or using API keys. Applies to both key creation and key use.
Each Blank account can keep up to three active API keys. Revoke an old one from Settings → API Keys before creating another.
The submit call used a different API key than the build call that created the submission intent. Submit with the same key you built with, or rebuild from scratch using the new key.
The API key gets you in the door, but the signed transaction also needs the creator/controller wallet’s signature. Rebuild, sign with the wallet returned in requiredUserSigner, then submit.
The submission intent record is missing the metadata that says which wallet has to sign. Recoverable, but not by retrying submit — call blank.launch.create() (or the matching staking call) to produce a fresh intent.
Another request with the same Idempotency-Key is still being processed. Wait for it to settle and check the result. If the original ended up failing, the lock is released automatically and your next retry goes through normally.
The account has too many pending launches that haven’t been submitted or expired. Submit the in-flight launches, or wait for them to expire (the build payload window is short — see “Payload expired”), then retry.
The creator wallet has blown past the launch-build quota. Back off and retry later, or double-check you’re passing the intended creator wallet — accidentally launching repeatedly from the same hot wallet is the usual cause.
Blank’s launch signer is temporarily over capacity. Server-side throttling, not your account. Honor the Retry-After response header and retry.
Blank pre-mines BLNK vanity mints for launches. Both errors mean no clean mint is available right now — wait and retry. The SDK surfaces these as transient 503s; an exponential backoff with a small cap is enough.
Basic launches on mainnet must go through a Jito bundle with bundleOnly: true. The SDK does this for you. If you’re hitting the HTTP submit endpoint directly, send both transport: "jito" and bundleOnly: true — leaving either off triggers one of these two errors. On devnet, use transport: "rpc".
The wallet signed, but the relay/submit step failed or the Jito bundle did not land before expiry. The thrown error keeps the signed transactions and the submission intent ID, so you can retry without prompting the wallet again:
await blank.launch.retrySubmit({ submissionIntentId, signedTransactions });
The SDK caught a submit failure it couldn’t classify. Log the X-Request-Id from the response and call blank.launch.retrySubmit({ submissionIntentId, signedTransactions }) if the error exposed those fields. If it didn’t, rebuild and sign again.