Tokens

A token in the PirateCrew API is a plain SPL mint with Metaplex Token Metadata attached — issued, named, and (optionally) supply-minted in a single VersionedTransaction. This is the right surface for one-off launches that don't need a bonding curve. For DBC + GOLD-quoted pools, see Pools. This page covers the token-create endpoint, authority revocation, and metadata reads.

Lifecycle

A token-create transaction does all of the following atomically:

1. Allocates and initializes the SPL mint with the requested decimals.
2. Creates the Metaplex Token Metadata v3 account (name, symbol, uri).
3. Mints initial_supply into the payer's ATA (created in the same tx).
4. Optionally revokes the freeze authority (default: yes) and/or the mint authority (default: no) at the end of the tx.

Because the payer is the token owner, mode=signed is rejected on POST /v2/tokens — the creator's wallet must sign with full authority.

NSFW moderation

If your front-end uploads an image and bakes the URL into uri, the image is already screened during a POST /v2/pools flow. The standalone POST /v2/tokens endpoint does not re-fetch and screen uri — you're responsible for hosting a reviewed image. Push to Storacha (or any other IPFS pinner) after passing your own checks.

Endpoints

Create request shape

{
  "payer": "YOUR_WALLET_PUBKEY",
  "name": "Black Pearl",           // 1-32 chars
  "symbol": "PEARL",               // 1-10 chars
  "decimals": 6,                   // 0-9, default 6
  "initial_supply": "1000000000",  // decimal string of raw units, minted to payer ATA
  "uri": "https://blackpearl.xyz/metadata.json",  // http(s) URL
  "revoke_mint_authority": false,  // default false — keep mint authority
  "revoke_freeze_authority": true, // default true  — remove freeze authority
  "mode": "unsigned"               // signed is rejected
}

Default revoke posture matches the meme-coin norm: no one can freeze, but the creator can still mint follow-on supply if needed. Set revoke_mint_authority: true at create time to lock supply forever.

Create example

curl -X POST https://api.piratecrew.fun/v2/tokens \
  -H "Authorization: Bearer $PIRATE_API_KEY" \
  -H "Idempotency-Key: 7b1e8c4f-…" \
  -H "Content-Type: application/json" \
  -d '{
    "payer": "YOUR_WALLET_PUBKEY",
    "name": "Black Pearl",
    "symbol": "PEARL",
    "decimals": 6,
    "initial_supply": "1000000000000000",
    "uri": "https://blackpearl.xyz/metadata.json",
    "revoke_mint_authority": false,
    "revoke_freeze_authority": true,
    "mode": "unsigned"
  }'

{
  "data": {
    "mode": "unsigned",
    "transaction": "AQABAo...",
    "mint_address": "MINT…",
    "metadata_address": "META…",
    "required_signers": {
      "mint_secret_key": [/* 64 bytes — ephemeral keypair for the new mint */]
    }
  },
  "meta": { "request_id": "req_…" }
}

The mint is an ephemeral keypair generated server-side — its only purpose is to sign its own account-creation instruction in the tx. Co-sign with both your wallet and mint_secret_key, then submit via POST /v2/transactions. After confirmation, the mint authority belongs to payer (your wallet) regardless of which key signed the account creation.

If you call POST /v2/tokens with mode: "signed" you get:

{
  "error": {
    "code": "bad_request",
    "message": "token-create requires the creator wallet to sign; use mode=unsigned"
  },
  "meta": { "request_id": "req_…" }
}

Revoking authority later

The two mint-vs-freeze flags on create are the cheap path. If you want to leave them in place initially and revoke later — for instance after a vesting cliff — use the standalone endpoint:

curl -X DELETE https://api.piratecrew.fun/v2/tokens/MINT…/authorities/mint \
  -H "Authorization: Bearer $PIRATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payer": "YOUR_WALLET_PUBKEY",
    "mode": "unsigned"
  }'

The path segment {type} is "mint" or "freeze" — there's no batched form, call twice if you need both. Unlike create, this endpoint does accept mode=signed (it's a single transfer-authority instruction), so a Privy-managed treasury can rotate authorities without a custom signer.

Reading metadata

curl https://api.piratecrew.fun/v2/tokens/$MINT \
  -H "Authorization: Bearer $PIRATE_API_KEY"

The response wraps a normalized token resource derived from a Helius getAsset lookup:

{
  "data": {
    "mint": "MINT…",
    "interface": "FungibleToken",
    "name": "Black Pearl",
    "symbol": "PEARL",
    "uri": "https://blackpearl.xyz/metadata.json",
    "decimals": 6,
    "supply": "1000000000000000",
    "mint_authority": "PAYER…",
    "freeze_authority": null,
    "status": "freeze_authority_revoked"
  },
  "meta": { "request_id": "req_…" }
}

Use it for token-picker UIs, balance dashboards, or anywhere you'd otherwise call getAsset directly. Caching the response client-side is fine — token metadata is effectively immutable after creation unless you explicitly update it on-chain.

Reference

• Pools — DBC-quoted pools when you want a launch curve, not a fixed-supply mint.
• Transaction Modes — why token-create rejects mode=signed.
• Live schema: /v2/docs.