Glossary

Reference for the terms used throughout the PirateCrew Blockchain API docs. Alphabetized.

API key

A Bearer token issued through developer.piratecrew.fun. Each key is backed by a row in the Supabase api_keys table and carries its own per-minute / per-day rate limits and an optional list of scopes that gate sensitive mode=signed endpoints. Keys are shown in full exactly once at creation — store them in a secrets manager.

Bonding curve / DBC pool

A Meteora Dynamic Bonding Curve pool. New tokens launch onto a curve denominated in GOLD; as buyers push the price up the curve, the pool accrues fees and surplus. When the pool hits its migration threshold (~$100k market cap) it graduates to DAMM v2. Pre-migration state is read via GET /v2/pools/{address} and GET /v2/pools/{address}/curve-progress.

DAMM v2

Meteora's Dynamic AMM v2 — the destination AMM that a DBC pool graduates into once it crosses the migration threshold. Both pre- and post-migration partner fees are claimed through the unified POST /v2/pools/{address}/fee-claims route (the kind field selects dbc, damm_v2, surplus, or split).

external_uid

Optional client-supplied identifier on every write request. The API persists it on the underlying resource and includes it on every webhook event tied to that resource. Use it to link an API resource to a row in your own ledger — a campaign ID, an order number, a launchpad job. Distinct from Idempotency-Key: the key is for safe retries, external_uid is for permanent cross-system linkage. See External UID.

GOLD

The platform's tradeable token. Mint: GoLDDqDRHcGZBiGPeXAYi5ougndqBNQSNXdNeT3re6gr. GOLD is the quote mint for every DBC pool launched on the platform, so every new-token price is denominated in GOLD rather than SOL.

veGOLD

Vote-escrow GOLD. Users receive veGOLD by locking GOLD via POST /v2/gold-locks; the amount and lock duration determine the veGOLD balance. veGOLD is non-transferable and is burned back to GOLD via DELETE /v2/gold-locks/{user} after the lock expires.

Idempotency-Key

A request header on every write endpoint. The API caches the response keyed on (api_key, sha256(body)); replays with the same key and body return the cached response, and reuse with a different body returns 409. Use a fresh v4 UUID per logical operation. See Idempotency.

Jito bundle

An atomic group of 1–5 already-signed transactions submitted together via POST /v2/transactions with bundle: true. Either all of them land in the same slot or none of them do — useful when a flow doesn't fit in a single 1232-byte Solana transaction.

Lifecycle

The coarse state of a submitted transaction, exposed as the lifecycle field on GET /v2/transactions/{signature}. One of unknown, submitted, processing, confirmed, finalized, failed. Most product UX should branch on lifecycle rather than the raw Solana confirmationStatus. See Transaction Lifecycle.

Keccak-256

The hash function used to build the airdrop merkle tree. Not SHA-256 — this is the Ethereum-compatible Keccak variant, chosen so the on-chain verify_merkle_proof instruction in the Pirates program can verify proofs without extra precompiles.

Merkle proof

The array of base58-encoded sibling hashes returned by GET /v2/merkle-trees/{id}/proofs/{wallet}. The claimer submits this proof to POST /v2/airdrops/{id}/claims together with their entry data; the on-chain program walks the proof up to the stored root to authorize the claim.

mpl-core NFT

A Metaplex Core asset — the modern single-account NFT format. There is no associated token account and no master edition; the asset lives in one program-owned account on program CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d. All NFTs minted through POST /v2/nfts are mpl-core assets.

Partner fee

The DBC creator's share of trading fees, accrued continuously as the pool trades. Claim via POST /v2/pools/{address}/fee-claims — pass kind: "dbc" pre-migration and kind: "damm_v2" after the pool graduates. Use GET /v2/pools/{address}/fee-metrics to read the current claimable balance.

PDA (Program Derived Address)

A deterministic address derived from a program ID plus a list of seeds. PDAs are owned by their program, never have a private key, and are addressable off-chain by anyone with the same seed inputs. Derive any Pirates-program PDA via POST /v2/pdas/{kind}. PDA kinds: platform, treasury, airdrop_config, claim_airdrop, user_nft_config, gold_lock_config, user_lock_config, gold_vault, ve_gold_mint, user_ve_gold.

Pirates program

The on-chain Anchor program at BpEjeUewpz8v3QTenXTwkknBBsXaRH37DW7x2jKmVrAg. It owns the platform's staking, airdrop, NFT, and gold-locking state. The IDL is bundled with the API (src/idl/pirates.json) and drives every PDA derivation and instruction builder.

Platform wallet (Privy)

The server-side signing wallet held in Privy and used when a request specifies mode: "signed". The wallet is configured via the PRIVY_PLATFORM_WALLET_ID env var and is the only signer used by server-signed flows; user-owned operations never touch it.

Platform ID

A short namespacing string (platform_id) included on most write requests. Pirates uses "pirate-crew" in production. The field exists so the same API surface can host multiple tenants — each tenant's PDAs hang off a distinct platform seed.

required_signers

A field returned in mode=unsigned responses listing ephemeral keypairs whose secret keys are inlined in the response. The client must co-sign with both its own wallet and every secret key in required_signers before broadcasting. Example: POST /v2/tokens returns a mint_secret_key because the new mint account is also a signer.

Scope

A string tag attached to an API key (e.g. fees:claim, airdrop:admin) that gates mode=signed on sensitive endpoints. unsigned mode never requires a scope. The wildcard * grants every scope. See Scopes & Permissions.

Surplus

The quote-token amount left in a DBC pool after migration that's still owed to the creator. Distinct from accrued trading fees. Withdraw via POST /v2/pools/{address}/fee-claims with kind: "surplus".

Storacha (web3.storage)

The IPFS uploader used for token metadata and airdrop manifest hosting. The server holds a Storacha space and issues short-lived UCAN delegations so that clients can upload directly to IPFS without proxying through the API.

UCAN

User Controlled Authorization Network — the capability-token format Storacha uses to scope an upload session to a specific DID and time window. The API server's UCAN proof is configured via the STORACHA_PROOF env var.

VersionedTransaction

Solana's transaction format with address-lookup-table support (MessageV0). Every mode=unsigned response returns the transaction as base64-encoded VersionedTransaction bytes — deserialize with VersionedTransaction.deserialize(Buffer.from(tx, "base64")) before signing.