FAQ

Why does mode=signed fail for stake / airdrop-claim / NFT mint / gold lock?

These actions transfer value or rights out of a user's wallet, and only that wallet can authorize them. The platform's Privy signer doesn't have authority over arbitrary user accounts — it can only sign for the platform wallet itself.

Concretely, mode=signed is rejected with a 400 on POST /v2/airdrops/{id}/claims, POST /v2/stakes, DELETE /v2/stakes/{asset}, POST /v2/nfts, DELETE /v2/nfts/{asset}, POST /v2/gold-locks, DELETE /v2/gold-locks/{user}, and POST /v2/tokens. Build the transaction with mode=unsigned, have the user sign it client-side, then submit via POST /v2/transactions. Server signing is only available for treasury / admin actions like fee claims and airdrop initialization.

What's the difference between GET /v2/pools/{address} and GET /v2/accounts/{address}?

GET /v2/pools/{address} returns a domain-decoded view of a Meteora pool: type discriminator (dbc or damm_v2), virtual reserves, partner fee balances, the migration target, and the curve-progress percentage. It only works for pool accounts and bundles the calls the launch UIs need.

GET /v2/accounts/{address} returns a generic view of any Solana account — owner, lamports, raw data length, and, when the account is owned by a known program, an attempt at Anchor decoding. Use it for arbitrary PDAs, mints, token accounts, or anything that isn't a pool.

Can I call the API from a browser?

You can, but you shouldn't expose a high-privilege key to the browser. Your API key is a Bearer secret — embedding it in a frontend bundle means anyone can scrape and reuse it. CORS is permissive enough for browser calls, but the recommended pattern is to proxy through your own backend, where the secret stays server-side.

If you genuinely need a public-facing key (e.g. for a static demo), generate one with read-only / no scopes, tight rate limits, and a short rotation interval.

How do I get higher rate limits?

The default Starter tier on each new key is intentionally conservative. To bump per-minute and per-day limits, ping the team on Discord #dev with your API key prefix, your expected request volume, and a sentence about what you're building. Bumps are granted manually; there's no self-serve upgrade today.

How do I request additional scopes?

Scopes (fees:claim, airdrop:admin, airdrop:write, *) gate server-signing endpoints and admin write paths. New keys ship with no scopes — fine for unsigned flows. To request a scope, same channel as rate-limit bumps: Discord #dev, share the key prefix and the route(s) you need to call. We add scopes to existing keys directly in Supabase rather than reissuing.

What happens to my Idempotency-Key if the request times out?

The middleware writes the (key, sha256(body)) row to idempotency_keys as soon as the request is accepted, before the handler runs. If the connection drops mid-response, retry the same request with the same Idempotency-Key and the same body — you'll get the cached final response if the original completed, or a 409 Conflict if it's still in flight or if the body hash doesn't match.

Conflict on body-hash mismatch is intentional: it means you reused a key for a different request, which is almost always a client bug. Use a fresh UUID per logical operation and only retry with the exact same payload.

Why does my token create fail with "image rejected"?

POST /v2/pools and POST /v2/tokens run every uploaded image through an NSFW classifier before pinning it to IPFS. Common rejection categories are explicit content, gore, and depictions of real-world hate symbols. The check is automated — if you believe it misfired on a benign image, host the image yourself, pass the existing URL as image, and the moderation step is skipped (you're attesting on your own).

How long does pool migration to DAMM v2 take?

The DBC curve runs until enough quote token has been bought to hit the market-cap target encoded in the curve config. From there, migration is a single transaction triggered by the first eligible call — usually within minutes of the threshold being crossed. Poll GET /v2/pools/{address}/curve-progress to watch the curve fill, and re-read GET /v2/pools/{address} to detect the type flipping from dbc to damm_v2 (or subscribe to the pool.migrated webhook).

Can I submit unsigned partial transactions and have you sign mine?

No. Server signing is all or nothing — mode=signed means the platform wallet builds, signs, and broadcasts a transaction it has full authority over. There's no flow where the server adds a partial signature to a tx that already has client signatures. If you need an atomic multi-signer flow, build the transaction client-side with the platform wallet as a co-signer using its public key, submit it through POST /v2/transactions with bundle: true for atomic landing, and coordinate the platform signature out-of-band.

Why isn't there a devnet-only API host?

The API service itself is a thin layer over RPC + Anchor + Supabase. Spinning up a parallel host would duplicate every key, every scope, and every Supabase table — for marginal benefit, since pointing the existing host at a devnet RPC via the rpcUrl override gives you the same result. The tradeoff is that Supabase state is shared across clusters; see Environments & Base URLs for the caveats.

What's the difference between a single submit and a Jito bundle?

POST /v2/transactions with a single transaction field sends a signed transaction to the standard Solana RPC. Fast, simple, and what you want 95% of the time.

POST /v2/transactions with bundle: true and a signed_transactions array (1–5 entries) packages those transactions into a Jito bundle and sends them to a block-engine endpoint. Bundles either all land in the same block atomically or none of them land. Use it when you need atomicity across multiple transactions (e.g. pool-create + first-buy), when you want priority through a tip, or when MEV protection matters. Jito bundles cost a tip and have a stricter expiry.

How do I cross-link from my docs to a specific endpoint in the API reference?

Every endpoint registered in the OpenAPI spec is rendered in the live reference at /v2/docs and in /v2/openapi.json. On ReadMe, the API reference pages are slugged by operationId — link to /reference/<operationId> to deep-link a single endpoint. From inside the guides, prefer a relative link to the closest narrative guide (e.g. Transaction Modes) and let readers click through to the reference from there.