Guides
  1. Concepts

Core Objects

Core Objects

The API is organized into noun-based REST resources under /v2. Each resource maps to one of the top-level on-chain entities below.

Response envelope

Every response is wrapped in a uniform envelope:

{
  "data":  { /* the resource, or an array of resources */ },
  "meta":  { "request_id": "req_…", "external_uid": "…", "metadata": { } }
}

List endpoints add has_more, next_cursor, and count to meta — see Pagination & limits. Errors use the same envelope with data replaced by error: { code, message, param?, doc_url? } — see Errors & retries.

Resource lifecycles

Every long-lived v2 resource — pool, airdrop, stake, gold lock, NFT, token, transaction — carries an explicit status field whose value comes from an enumerated state machine. Each state transition fires a webhook event. See Resource lifecycles for the full state machines and Webhooks for delivery semantics.

Resources

ResourcePathWhat it does
Pool/v2/poolsCreate + list + read DBC and DAMM v2 pools (polymorphic on type)
Fee claim/v2/pools/{address}/fee-claimsUnified claim route; kind discriminator selects DBC / DAMM v2 / surplus / split
Airdrop/v2/airdropsInit, list, read; claim + admin-withdraw sub-routes
Merkle tree/v2/merkle-treesFirst-class trees + /proofs/{wallet} lookup
Stake/v2/stakesPOST to stake an NFT; DELETE /v2/stakes/{asset} to unstake
NFT/v2/nftsMint via POST; burn via DELETE /v2/nfts/{asset}
Gold lock/v2/gold-locksLock via POST; unlock via DELETE /v2/gold-locks/{user}
Token/v2/tokensSPL + Metaplex metadata in one tx; read + revoke-authority sub-routes
Transaction/v2/transactionsSubmit; GET /v2/transactions/{signature} for status
Swap / Swap quote/v2/swaps, /v2/swap-quotesJupiter swap + standalone quote
PDA/v2/pdas/{kind}Each PDA kind is its own typed sub-resource
Account/v2/accountsRaw account read, batch read
Webhook subscription/v2/webhook-subscriptionsCRUD for delivery endpoints
Event/v2/webhook-event-typesCanonical catalog of every event we can fire

Pool

A Meteora pool — either a pre-migration DBC bonding curve or a post-migration DAMM v2 liquidity position. Pools are a polymorphic resource with a type: "dbc" | "damm_v2" discriminator on the response.

  • Create: POST /v2/pools.
  • List: GET /v2/pools?limit=20&cursor=… (cursor-paginated).
  • Read: GET /v2/pools/{address}.

Stable fields: address, type, status (pending | live | migration_triggered | migrated | failed), base_mint, quote_mint, config_key, migration_progress_bps, partner_fees_quote, partner_fees_base, surplus_quote. Amounts are decimal strings.

Fee claim

A fee position — the creator's claim against an underlying pool. A single endpoint handles all four claim variants via a kind discriminator:

  • Claim: POST /v2/pools/{address}/fee-claims with kind: "dbc" | "damm_v2" | "surplus" | "split".
  • Read claimable: GET /v2/pools/{address}/fee-claims returns current claimable balance in both base and quote.

The split kind takes a splits[] array of 2–10 recipients whose bps must sum to exactly 10000.

Airdrop

A merkle-rooted token distribution. Merkle trees are a first-class resource separate from the airdrop itself.

  • Build tree: POST /v2/merkle-trees (up to 50,000 entries) — computes the root and persists the tree.
  • Init airdrop: POST /v2/airdrops — writes the root into a new airdrop config PDA.
  • Lookup proof: GET /v2/merkle-trees/{id}/proofs/{wallet}.
  • Claim: POST /v2/airdrops/{id}/claims — user-signed only.

Stable airdrop fields: mint, airdrop_config_pda, merkle_root, total_entries, claimed_count, vault_pda, status (tree_built | initialized | claiming | fully_claimed | vault_drained).

Stake

An on-chain NFT stake. Each stake is a resource keyed by asset address.

  • Stake: POST /v2/stakes — user-signed only.
  • Unstake: DELETE /v2/stakes/{asset} — user-signed only.
  • Read: stake state lives on the mpl-core asset's plugin, not in our DB. Fetch GET /v2/accounts/{asset} and decode the plugin layer client-side. (GET /v2/stakes/{wallet} exists as a placeholder that returns this guidance — there is no off-chain index.)

Status enum: unstaked | staked | burned.

NFT

An mpl-core asset minted under the Pirates program. Single-account NFT (no token account, no master edition). The program at CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d is the owner.

  • Mint: POST /v2/nfts — user-signed only.
  • Burn: DELETE /v2/nfts/{asset} — user-signed only.
  • Stake / unstake: via the Stake resource above.
  • Read: derive user_nft_config via POST /v2/pdas/user_nft_config and fetch with GET /v2/accounts/{address}. Asset state lives entirely on-chain; there is no direct GET /v2/nfts/{asset}.

Status enum: minted | staked | burned.

Gold lock

A vote-escrow lock. The user deposits GOLD into a vault PDA and receives non-transferable veGOLD proportional to amount and lock duration.

  • Lock: POST /v2/gold-locks — user-signed only.
  • Unlock: DELETE /v2/gold-locks/{user} once the lock expires — user-signed only.
  • Read: derive user_lock_config and user_ve_gold PDAs (POST /v2/pdas/user_lock_config, POST /v2/pdas/user_ve_gold) and fetch each with GET /v2/accounts/{address}. Lock state is fully on-chain.

Status: unlocked | locked | eligible_for_unlock. GOLD mint is GoLDDqDRHcGZBiGPeXAYi5ougndqBNQSNXdNeT3re6gr.

Token

An SPL mint plus its Metaplex metadata account. POST /v2/tokens bundles SPL mint initialization, metadata creation, and (optionally) authority configuration into a single transaction.

  • Create: POST /v2/tokens — returns the mint_secret_key in required_signers.
  • Revoke authority: DELETE /v2/tokens/{mint}/authorities/{type}.
  • Read: GET /v2/tokens/{mint}.

Status: created | mint_authority_revoked | freeze_authority_revoked | fully_immutable. Stable metadata fields: mint, name, symbol, uri, seller_fee_basis_points, mint_authority, freeze_authority.

Transaction

Any Solana VersionedTransaction — built by a v2 route, signed locally, then submitted back to the API for broadcast.

  • Submit: POST /v2/transactions (single tx, or set bundle: true for an atomic Jito bundle of up to 5 txs).
  • Simulate: POST /v2/transaction-simulations.
  • Poll status: GET /v2/transactions/{signature}.

Status / lifecycle enum: unknown | submitted | processing | confirmed | finalized | failed. See Transaction Lifecycle and Transaction Modes.

Merkle tree

A persisted keccak256 merkle tree backing an airdrop. Trees are first-class resources so the same tree can back multiple airdrops or be inspected without going through /airdrops.

  • Build: POST /v2/merkle-trees.
  • Read: GET /v2/merkle-trees/{id}.
  • Lookup proof: GET /v2/merkle-trees/{id}/proofs/{wallet}.

Webhook subscription

A delivery endpoint for resource lifecycle events. Full CRUD at /v2/webhook-subscriptions. See Webhooks and Resource lifecycles.

Event

A resource lifecycle event — pool.live, airdrop.claimed, transaction.finalized, etc. The canonical catalog (with detection mode for each) is published at GET /v2/webhook-event-types. Events are persisted to the events table; the delivery worker fans them out to active subscriptions.

Cross-references

These descriptions cover the stable, externally-visible shape of each object. The full request and response schemas for every endpoint — including every optional field and enum value — live in the OpenAPI document at /v2/openapi.json.