CollectorCrypt API

Bridge physical trading cards and blockchain — buy, sell, and trade collectible card NFTs on Solana, open mystery gacha packs, redeem NFTs for real cards, and swap assets peer-to-peer.

Marketplace Base URL:

https://api.collectorcrypt.com

Marketplace Devnet URL:

https://dev-api.collectorcrypt.com

Gacha Base URL:

https://gacha.collectorcrypt.com

Gacha Devnet URL:

https://dev-gacha.collectorcrypt.com

Key Concepts

Product Suite

Marketplace — buy/sell/trade collectible card NFTs using USDC on Solana
Gacha Machine — mystery pack system; spend USDC for randomized Pokemon card NFTs with VRF-verified fairness
Vault — bridge NFTs ↔ physical cards; deposit real cards to mint NFTs, burn NFTs to ship physical cards
Swap — peer-to-peer on-chain asset swaps via escrow (NFTs, pNFTs, cNFTs, SPL tokens)
Launchpads — drop pages for minting new collectible releases
Bidder — eBay bid automation; deposit funds, service bids and tokenizes won cards

Solana Programs

Program	ID
Marketplace	`CcmRKTuZCGJBWQwMHvDYApBRvSZNHqGJXkznqpDTSQUr`
Swap	`CCSwaptcDXtfjyRMYBqavqBwiW162yXFAJrXN53UuENC`

NFT Types Supported

Programmable NFTs (pNFTs) — Metaplex standard with enforced royalties; use
```
tokenStandard: "Pnft"
```
Compressed NFTs (cNFTs) — Metaplex Bubblegum merkle-tree structure; use
```
tokenStandard: "Cnft"
```
Metaplex Core (
nftStandard: "core"
) — single-account standard; many live listings are Core (browse responses return
```
"nftStandard": "core"
```
). For Core listings, omit
tokenStandard
from buy/list/offer bodies — do NOT pass
```
"Pnft"
```
/
```
"Cnft"
```
. Only send
```
tokenStandard
```
when the asset is actually pNFT or cNFT.

Currency

All marketplace and gacha transactions use USDC (SPL Token) on Solana. Shipping fees accept USDC or USDT. Gas fees paid in SOL.

Marketplace prices are in whole USDC (e.g.,

"price": 25

means $25.00 USDC).

Transaction Pattern (Marketplace & Shipping)

Three-step flow:

Build — POST to API endpoint, receive base64-encoded unsigned transaction(s)
Sign — Sign with the Solana wallet (Phantom/Solflare, or the Starchild wallet helper — see below)
Broadcast — POST signed transaction to
```
/marketplace/broadcast
```

HTTP status — accept BOTH
200
and
201
as success. Verified live:

/marketplace/buy

and

/marketplace/broadcast

return 201
, not

. Treat any 2xx as success; do not hard-check

== 200

Response body may be raw base64 text, NOT JSON.

/marketplace/buy

with

fundingSource: "wallet"

can return the unsigned transaction as a plain-text body. Parse defensively:

python

text = response.text
try:
    data = response.json()
    tx = data.get("transaction") or data.get("serializedTransaction")
except Exception:
    tx = text  # body was the raw base64 transaction

Starchild wallet signing returns snake_case
signed_transaction
. When signing with the platform wallet:

python

from core.skill_tools import wallet
signed = wallet.wallet_sol_sign_transaction(unsigned_tx)
# → {"signed_transaction": "<base64>", "encoding": "base64"}
signed_tx = signed.get("signed_transaction") or signed.get("signedTransaction")

Look for

signed_transaction

first, then the camelCase variant. Feed

signed_tx

into

/marketplace/broadcast

as the

signedTransaction

field.

Gacha Rarity Tiers

Rarity	Probability
Epic	1%
Rare (High)	4%
Uncommon (Mid)	15%
Common (Low)	80%

VRF (Verifiable Random Function)

Gacha rolls use a Verifiable Random Function for tamper-proof, provably-fair results. Selection is two-stage:

Roll → tier: a uniform integer roll in the range 1–100,000,000, seeded by the player's own wallet signature on the open transaction, maps to a rarity tier via the machine's configured weights (see
```
tierRanges
```
in
```
/api/machines
```
).
Card → within tier: a provable selection picks the specific NFT inside that tier.

The seed (wallet signature) and result are committed to Solana in the award transaction's on-chain memo, preventing prediction or manipulation. Verify independently:

```
GET /api/vrf/verify?memo=YOUR_MEMO
```
— returns the proof, public key, transaction signature, and whether the stored roll matches the recomputed roll.
```
/verify-selection/YOUR_MEMO
```
— browser-side replay of the card selection against the on-chain memo.

The docs do not name a specific VRF algorithm; don't assert one.

How to Call

Gacha API — No API Key (the key does not exist)

There is no API key. Do not set
CC_API_KEY
, do not send an
x-api-key
header, and do not try to obtain a key — the CollectorCrypt team has confirmed no key system exists. Every gacha endpoint, reads and writes alike, is called with no authentication.

bash

# Reads AND writes — no auth header of any kind
curl -s "https://gacha.collectorcrypt.com/api/machines"
curl -s -X POST "https://gacha.collectorcrypt.com/api/generatePack" \
  -H "Content-Type: application/json" \
  -d '{"playerAddress":"WALLET_PUBKEY"}'

Ignore the docs' authentication section. The public docs say "Each request must include a valid
x-api-key
header" and reference a partner "slug." That does not reflect reality — confirmed both by the team (no key system exists) and by live testing (
/api/generatePack
returns
200
with no header). There is nothing to request and no header to add.

Without a key, generated transactions carry a

cc-<uuid>

memo. Security comes from the wallet signature, not from any API credential — nothing executes until the user signs the transaction this API hands back.

Reference implementation: Gacha Starter Demo — https://github.com/daxherrera/gacha-starter (full pack → sign → submit → open flow). Try every call live on devnet at

https://dev-gacha.collectorcrypt.com

(fund a devnet wallet via the USDC faucet: https://spl-token-faucet.com/?token-name=USDC-Dev).

Marketplace API — No Auth for Reads

Public GET endpoints (browse listings) need no authentication. Write endpoints return unsigned transactions for wallet signing — no API key involved.

bash

# Browse listings — no auth, 5s cache for unauthenticated requests
curl -s "https://api.collectorcrypt.com/marketplace?page=1&step=20&categories=Pokemon"

# Create listing — returns base64 unsigned transaction
curl -s -X POST "https://api.collectorcrypt.com/marketplace/list" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "YOUR_SOLANA_ADDRESS",
    "cardId": "CC_CARD_DB_ID",
    "nftAddress": "NFT_MINT_ADDRESS",
    "currency": "USDC",
    "price": 50
  }'

Shipping API — Two Auth Tracks

Track A — Privy Identity Token:

Authorization: Bearer <privy-identity-token>

Track B — Sign-In With Solana (SIWS):

```
POST /auth/wallet/nonce
```
— get nonce + message to sign
Sign message with wallet (ed25519, base58)
```
POST /auth/wallet/verify
```
— exchange signature for access/refresh tokens

bash

# Step 1: Get nonce
curl -s -X POST "https://api.collectorcrypt.com/auth/wallet/nonce" \
  -H "Content-Type: application/json" \
  -d '{"wallet": "YOUR_PUBKEY", "partnerAppId": "your-slug", "domain": "your-app.com", "uri": "https://your-app.com"}'

# Step 3: Verify and get tokens
curl -s -X POST "https://api.collectorcrypt.com/auth/wallet/verify" \
  -H "Content-Type: application/json" \
  -d '{"message": "<message-from-nonce>", "signature": "<base58-ed25519-signature>"}'
# Returns: {"accessToken": "cca_...", "refreshToken": "ccr_...", "expiresAt": ...}

Token management:

Access token lifetime: 15 minutes

Refresh:

POST /auth/wallet/refresh

with

{"refreshToken": "..."}

Logout:
```
POST /auth/wallet/logout
```
Track B limitation: crypto payment only (no card payments), Solana signatures only

Intent Routing

Marketplace

Base:

https://api.collectorcrypt.com

All POST endpoints return base64-encoded unsigned Solana transaction(s). Sign with wallet, then broadcast via

/marketplace/broadcast

List an NFT —

POST /marketplace/list

Field	Type	Required	Description
`wallet`	string	yes	Seller's Solana address
`cardId`	string	yes	CollectorCrypt card DB ID
`nftAddress`	string	yes	NFT mint address
`currency`	string	yes	`"USDC"`
`price`	number	yes	Listing price in USDC
`tokenStandard`	enum	no	`"Pnft"` or `"Cnft"`
`userHasSol`	boolean	no	If `false` , backend pays fees

Errors:

(on-chain error),

(already listed)

Cancel a Listing —

POST /marketplace/cancel-listing

Field	Type	Required	Description
`wallet`	string	yes	Caller's wallet
`tokenMint`	string	yes	NFT mint address
`seller`	string	no	Defaults to `wallet`

Errors:

(on-chain error),

(no listing found)

Update a Listing Price —

POST /marketplace/update-listing

Field	Type	Required	Description
`wallet`	string	yes	Seller's wallet
`tokenMint`	string	yes	NFT mint address
`newPrice`	number	yes	Updated price in USDC
`coin`	string	yes	`"USDC"`

Errors:

(price unchanged or on-chain error),

(no listing found)

Buy an NFT —

POST /marketplace/buy

Field	Type	Required	Description
`wallet`	string	yes	Buyer's wallet
`nftAddress`	string	yes	NFT mint address
`price`	number	yes	Listed price in USDC
`currency`	string	yes	`"USDC"`
`tokenStandard`	enum	no	`"Pnft"` or `"Cnft"` — omit for Metaplex Core listings ( `nftStandard: "core"` )
`sellerWallet`	string	no	Resolved from DB if omitted
`fundingSource`	enum	no	`"wallet"` (default) or `"escrow"`

Success status is
200
OR
201
(live buys return

). Response body may be raw base64 text rather than JSON — parse defensively (see Transaction Pattern above).

```
fundingSource: "wallet"
```
→ single base64 unsigned transaction (JSON
```
{"transaction": "..."}
```
or plain base64 text)

fundingSource: "escrow"

→

{"transactions": ["BASE64_WITHDRAW_TX", "BASE64_BUY_TX"], "fundingSource": "escrow"}

Escrow requires minimum

price × 1.02

USDC balance.

Errors:

(on-chain error, insufficient escrow),

(card/listing not found),

(owner changed)

End-to-End Buy Recipe (tested live)

python

import requests
from core.skill_tools import wallet

BASE = "https://api.collectorcrypt.com"
buyer = "YOUR_WALLET_PUBKEY"

# 1. Find a listed item, cheapest first
listings = requests.get(f"{BASE}/marketplace",
    params={"page": 1, "step": 1, "marketplaceStatus": "Buy now", "orderBy": "listedPriceAsc"}
).json()["filterNFtCard"]
item = listings[0]
mint   = item["nftAddress"]
price  = float(item["listing"]["price"])
seller = item["owner"]["wallet"]
std    = item.get("nftStandard")  # "core" | "Pnft" | "Cnft"

# 2. Build buy tx. Omit tokenStandard for Core listings.
body = {"wallet": buyer, "nftAddress": mint, "price": price,
        "currency": "USDC", "sellerWallet": seller}
if std in ("Pnft", "Cnft"):
    body["tokenStandard"] = std
r = requests.post(f"{BASE}/marketplace/buy", json=body)
assert r.status_code in (200, 201)              # buy returns 201
try:    unsigned = r.json().get("transaction") or r.json().get("serializedTransaction")
except Exception: unsigned = r.text             # may be raw base64

# 3. Sign with Starchild wallet (snake_case key)
signed = wallet.wallet_sol_sign_transaction(unsigned)
signed_tx = signed.get("signed_transaction") or signed.get("signedTransaction")

# 4. Broadcast
b = requests.post(f"{BASE}/marketplace/broadcast",
    json={"wallet": buyer, "signedTransaction": signed_tx, "nftAddress": mint})
assert b.status_code in (200, 201) and b.json().get("success")  # broadcast returns 201
sig = b.json()["signature"]

# 5. Verify on Solana RPC — the SOURCE OF TRUTH (see below)
status = requests.post("https://api.mainnet-beta.solana.com", json={
    "jsonrpc": "2.0", "id": 1, "method": "getSignatureStatuses",
    "params": [[sig], {"searchTransactionHistory": True}]}
).json()["result"]["value"][0]
assert status and status["err"] is None and status["confirmationStatus"] == "finalized"

Verify via Solana RPC signature status, not a marketplace refetch. Marketplace metadata refresh lags after a buy, and there is no

nftAddress

lookup filter (

search=<mint>

is fuzzy and may not reflect the new owner immediately). The authoritative post-broadcast check is

getSignatureStatuses

on the broadcast

signature

json

{"confirmationStatus": "finalized", "err": null, "status": {"Ok": null}}

err == null

(and

confirmationStatus

confirmed

finalized

) means the buy settled on-chain. Only fall back to a marketplace refetch for display, never as the success gate.

Regression fixture — a real buy that succeeded (use to smoke-test the flow):

Field	Value
Item	2017 #024 POKE BALL PSA 9 — Pokémon Japanese Sun & Moon, Ash vs. Team Rocket Deck Kit
Price	19 USDC
NFT mint	`4AWreh7pqVb4jhANAXFz2fwSPKqWr5ZAFMgaAFWZS9nk`
Seller	`FfveJgtFmGPCSazkjicf21WLk9rdUaMsownVVA8LRhwf`
Broadcast signature	`5SwxeuWGjWbiAFq8YVN3Qsw1PXnKXBakKA2ykgccc78gg6JkGnyi48StezcijXmgWHyGWvojq8TYmTXJoC9XnbjH`
Solana status	`finalized` , `err: null`

Make an Offer —

POST /marketplace/make-offer

Field	Type	Required	Description
`wallet`	string	yes	Buyer's wallet
`cardId`	string	yes	CollectorCrypt card DB ID
`nftAddress`	string	yes	NFT mint address
`price`	number	yes	Offer price in USDC
`currency`	string	yes	`"USDC"`
`tokenStandard`	enum	no	`"Pnft"` or `"Cnft"`
`userHasSol`	boolean	no	Backend fee payer if `false`
`ownerWallet`	string	no	Current NFT owner
`collectionHash`	string	no	cNFT collection hash

Errors:

(can't determine owner or on-chain error)

Cancel an Offer —

POST /marketplace/cancel-offer

Field	Type	Required	Description
`wallet`	string	yes	Buyer's wallet
`nftAddress`	string	yes	NFT mint address
`keepInEscrow`	boolean	no	If `true` , USDC stays in escrow; default `false`

Backend auto-sets

keepInEscrow: true

if wallet has insufficient SOL for rent.

Errors:

(no active offer found)

Update an Offer —

POST /marketplace/update-offer

Field	Type	Required	Description
`wallet`	string	yes	Buyer's wallet (signer)
`nftAddress`	string	yes	NFT mint address
`currency`	string	yes	`"USDC"`
`buyer`	string	yes	Buyer's wallet (typically = `wallet` )
`price`	number	yes	New offer price in USDC

Important: Escrow must already contain the full new amount — this instruction does NOT transfer additional USDC.

Errors:

(price unchanged, no escrow, insufficient balance, on-chain error),

(offer not found)

Accept an Offer —

POST /marketplace/accept-offer

Field	Type	Required	Description
`wallet`	string	yes	Seller's wallet (NFT owner)
`nftAddress`	string	yes	NFT mint address
`buyer`	string	yes	Buyer's wallet
`currency`	string	yes	`"USDC"`
`price`	number	yes	Offer price in USDC
`tokenStandard`	enum	no	`"Pnft"` or `"Cnft"`
`userHasSol`	boolean	no	Backend fee payer if `false`

cNFT edge case: If the cNFT is currently listed, returns:

json

{
  "requiresCancelListing": true,
  "cancelListingTx": "BASE64_CANCEL_LISTING_TX",
  "message": "This cNFT is currently listed. Please sign..."
}

Sign the cancel-listing tx first, then re-call accept-offer.

Errors:

(price drift, on-chain error),

(offer not found)

Browse Listings —

GET /marketplace

Public, no auth required. 5-second cache for unauthenticated requests.

Pagination:

Param	Type	Default	Description
`page`	integer	1	1-indexed page
`step`	integer	100	Page size (max 100)

Filters (all optional):

Param	Type	Description
`search`	string	Substring match against itemName, nftAddress, gemrateCardName, gradingID. This is the only way to look up by mint — there is NO `nftAddress` query param ( `GET /marketplace?nftAddress=<mint>` returns `400` ). Use `search=<mint>` instead.
`ownerAddress`	string	Filter by owner wallet
`hideOwned`	boolean	Hide caller's own cards (requires auth)
`favoritesOnly`	boolean	Only favorited cards (requires auth)
`followingOnly`	boolean	Only from followed users (requires auth)
`followingOf`	string	Cards owned by users that this wallet follows
`marketplaceStatus`	CSV	`Buy now` , `Has offers`
`marketplaceSource`	CSV	`CC` , `ME`
`marketplaceTags`	CSV	Global tag names (e.g., `Hot` , `Featured` )
`listPriceMin` / `listPriceMax`	number	USDC price range
`insuredValueMin` / `insuredValueMax`	number	Insured value range
`yearMin` / `yearMax`	integer	Card year range
`categories`	CSV	`Pokemon` , `Baseball` , `Basketball` , `Football` , `Magic The Gathering` , `Yu-Gi-Oh!` , `Lorcana` , `One Piece` , `Non-Sport` , etc.
`cardType`	CSV	`Card` , `Comic` , `ComicRaw` , `Game` , `Merch` , `Raw` , `Sealed`
`blockchain`	CSV	`Solana` , others
`authenticated`	boolean	Only authenticated cards
`autographed`	boolean	Only autographed cards
`burnt`	boolean	Include burned cards (default excludes)
`grade`	string	Substring match
`genericGradeMin` / `genericGradeMax`	number	Numeric grade range
`gradingCompany`	CSV	`PSA` , `Beckett` , `CGC` , `SGC` , `TAG` , `CSG` , `KSA` , `PSA/DNA` , `UDA` , `Steiner` , `BBCE` , `Rare Edition` , `Not graded`
`set` / `format` / `language` / `productCode`	string	Substring match for sealed/comic metadata
`pokemon`	string	Word-boundary match against gemrateCardName
`ccBuyback`	boolean	Only cards with active CC buyback
`gemrateSet` / `gemrateGrade` / `gemrateCardName` / `gemrateSpecId` / `gemrateParallel`	string	Gemrate-specific filters

Sort —
orderBy
values:

dateAsc

dateDesc

nameAsc

nameDesc

priceAsc

priceDesc

(insured value),

yearAsc

yearDesc

listedDateAsc

listedDateDesc

listedPriceAsc

listedPriceDesc

Default:

listedDateDesc

Response:

json

{
  "filterNFtCard": [
    {
      "id": "card_db_id",
      "itemName": "...",
      "nftAddress": "NFT_MINT_ADDRESS",
      "nftStandard": "Pnft",
      "blockchain": "Solana",
      "category": "Pokemon",
      "type": "Card",
      "year": 1999,
      "grade": "10",
      "gradeNum": 10,
      "gradingCompany": "PSA",
      "gradingID": "...",
      "insuredValue": "...",
      "listing": {
        "price": "25",
        "currency": "USDC",
        "marketplace": "CC",
        "sellerId": "...",
        "createdAt": "ISO_DATE"
      },
      "offers": [{"id": "offer_id"}],
      "owner": {
        "id": "user_id",
        "name": "...",
        "wallet": "OWNER_WALLET_ADDRESS"
      },
      "images": {
        "front": "URL",
        "frontM": "URL",
        "frontS": "URL",
        "back": "URL",
        "backM": "URL",
        "backS": "URL"
      }
    }
  ],
  "findTotal": 1234,
  "total": 50000,
  "totalPages": 25,
  "cardsQtyByCategory": {"Pokemon": 800, "Baseball": 200}
}

```
listing
```
is
```
null
```
when unlisted
```
offers
```
is array of active offer IDs
```
findTotal
```
= total matching filter;
```
total
```
= total marketplace cards overall
```
cardsQtyByCategory
```
= per-category count (excludes
```
categories
```
filter)

Broadcast a Transaction —

POST /marketplace/broadcast

Field	Type	Required	Description
`wallet`	string	yes	Signer wallet address
`signedTransaction`	string	yes	Base64-encoded signed transaction
`nftAddress`	string	no	Triggers metadata refresh after 5s

Success status is
200
OR
201
(live broadcasts return

). Response:

json

{
  "success": true,
  "signature": "SOLANA_TRANSACTION_SIGNATURE",
  "message": "Transaction broadcast successfully"
}

Don't treat the

as a failure — check

success === true

/ presence of

signature

, not the status code.

Insufficient funds recovery: If broadcast returns

with

"code": "INSUFFICIENT_FUNDS_RETRYABLE"

, rebuild the original transaction with

userHasSol: false

so the backend pays fees, then re-sign and re-broadcast.

Validation: Transaction is validated against an allow-list of program IDs before submission.

Errors:

(invalid transaction, insufficient funds retryable, submission failure),

(program ID not on allow-list)

Gacha Machine

Base:

https://gacha.collectorcrypt.com

Method	Endpoint	Primary Params	Description
GET	`/api/status`	—	Machine operational status (open/closed)
GET	`/api/stock`	—	NFT inventory counts by rarity per machine
GET	`/api/machines`	—	Full config for all machines: pricing, `odds` , `tierRanges` (roll→tier bounds), live `stock` , `instantBuyback` %, and `ev` (rarity-weighted expected insured value)
GET	`/api/getNfts`	`code` , `rarity` , `page` , `limit`	Available NFTs with filtering
POST	`/api/generatePack`	Body: `playerAddress` , `packType` , `turbo` , `altPlayerAddress`	Create purchase transaction for one pack
POST	`/api/generateYoloPacks`	Body: `count` (1-100), `packType` , `playerAddress` , `turbo` , `altPlayerAddress`	Batch purchase multiple packs
POST	`/api/openPack`	Body: `memo`	Open purchased pack, receive NFT
POST	`/api/buyback`	Body: `playerAddress` , `nftAddress` , `altRecipient`	Sell NFT back for USDC (within 72 hours)
GET	`/api/buyback/check`	`memo`	Check buyback completion status
GET	`/api/buyback/available`	`wallet` , `nft`	Pre-check NFT buyback eligibility + refund `amount` (before building a tx)
GET	`/api/pack/status`	`memo`	Full pack lifecycle: purchase, NFT send (incl. `prize_tier` , `insured_value` , `vrf_proof` ), and buyback history
POST	`/api/submitTransaction`	Body: `signedTransaction` (base64)	Submit signed transaction to Solana
POST	`/api/generateGift`	Body: `sender` , `receiver` , `packType` , `count`	Gift packs to another wallet
GET	`/api/getGifted`	`wallet`	Gift history (sent/received)
GET	`/api/purchasedPacks`	`wallet`	Pack counts by type (purchased vs gifted, used vs unused)
POST	`/api/generatePurchasedPack`	Body: `publicKey` , `packType` , `ledger`	Create sign challenge for opening gifted/purchased packs
POST	`/api/usePurchasedPack`	Body: `nonce` , `packType` , `publicKey` , `signature` / `transactionSignature` , `ledger`	Consume purchased pack after signing, returns memo
GET	`/api/getAllWinners`	`timestamp` , `slug` , `epic` , `packType` , `count`	Recent winners with optional filtering
GET	`/api/vrf/verify`	`memo`	Verify VRF proof for a roll

Gacha Response Shapes

generatePack response:

json

{"memo": "slug-uuid", "transaction": "base64_encoded_transaction"}

The

memo

cc-<uuid>

(there is no API key, so no partner slug prefix applies). Body is

{playerAddress, packType?, turbo?, altPlayerAddress?}

—

packType

defaults to

pokemon_50

(use

pokemon_250

for legendary).

openPack response (normal win):

json

{
  "success": true,
  "transactionSignature": "...",
  "nft_address": "...",
  "nftWon": {
    "content": {
      "metadata": {"name": "...", "description": "...", "attributes": []}
    }
  },
  "points": 0,
  "roll": 12345678,
  "rarity": "Epic|Rare|Uncommon|Common"
}

roll

is an integer in the range 1–100,000,000 (NOT a fraction).

nftWon

is nested under

content.metadata

— there is no top-level

name

image

openPack response (turbo-mode buyback, Common roll): adds

"code": "TURBO_MODE_BUYBACK"

and

"buybackAmount": 42500000

(USDC base units) — the Common NFT is auto-sold instead of delivered.

openPack response (payment not yet confirmed):

json

{"success": true, "code": "WAITING_FOR_WEBHOOK", "memo": "slug-uuid-string"}

Do NOT assume an NFT was delivered on this response — poll

GET /api/pack/status?memo=...

(or retry

openPack

) until the win resolves.

openPack is idempotent: calling it again on an already-opened pack returns the original result (same

transactionSignature

nftWon

points

rarity

) — safe to retry.

Prize tier mapping (

pack/status

and

getAllWinners

return numeric

prize_tier

;

openPack

returns human-readable

rarity

= Epic,

= Rare,

= Uncommon,

= Common.

buyback response:

json

{
  "serializedTransaction": "base64",
  "refundAmount": 42500000,
  "memo": "..."
}

Shipping / Vault Redemption

Base:

https://api.collectorcrypt.com

Method	Endpoint	Primary Params	Description
POST	`/redeem/estimate`	Body: `nftAddresses` , `shippingAddressId`	Fee estimate without creating shipment; returns `price` , `insurancePrice` , `feesPrice` , `shippingPrice` , `total` , `numberOfCards` , `breakdown`
POST	`/redeem/prepare`	Body: `nftAddresses` , `shippingAddressId` , `coin` ( `USDC` \| `USDT` ), `deliveryCompany` , `comment` , `insurance`	Create pending shipment, returns unsigned transactions
POST	`/blockchain/:outboundShipmentId/burn`	Body: `transactions` (base64 signed), `evmTransactions`	Broadcast signed burn transactions; returns `id` , `status` , `transactionUrls`
GET	`/outbound-shipment`	—	List user shipments
GET	`/outbound-shipment/:id`	`id`	Get specific shipment status

Shipping Address Management

Method	Endpoint	Description
GET	`/shipping-address`	List saved addresses
GET	`/shipping-address/:id`	Get specific address
POST	`/shipping-address/create`	Create new address
PATCH	`/shipping-address/update/:id`	Update address
DELETE	`/shipping-address/:id`	Delete address

Shipping Rates

Region	Base	Each Additional	Signature	Pack Surcharge
USA	$5.99	$3.00	+$3.00 (value >= $500)	$0.18/pack
Canada	$20.99	$3.00	Included	$0.25/pack
Europe	$29.99	$3.00	Included	$0.25/pack
Australia/NZ	$34.99	$3.00	Included	$0.25/pack
Rest of World	$34.99	$3.00	Included	$0.25/pack

Insurance auto-applies at 0.5% of declared value when package exceeds $5,000.

Redeem/Prepare Response Shape

json

{
  "outboundShipmentId": "shipment_...",
  "transactions": ["<base64-unsigned-tx>"],
  "evmTransactions": [],
  "totalCost": 14.99,
  "submitUrl": "/blockchain/shipment_.../burn",
  "breakdown": {
    "region": "USA",
    "declaredValue": 700,
    "numberOfCards": 10,
    "lines": [
      {"code": "shipping_base", "label": "Base shipping (USA, first card)", "amount": 5.99, "unitPrice": 5.99}
    ]
  }
}

Auth (SIWS — Sign-In With Solana)

Base:

https://api.collectorcrypt.com

Method	Endpoint	Primary Params	Description
POST	`/auth/wallet/nonce`	Body: `wallet` , `partnerAppId` , `domain` , `uri`	Get nonce + EIP-4361 signing message
POST	`/auth/wallet/verify`	Body: `message` , `signature` (base58 ed25519)	Exchange signature for access + refresh tokens
POST	`/auth/wallet/refresh`	Body: `refreshToken`	Refresh expired access token
POST	`/auth/wallet/logout`	Body: `refreshToken` (+ access token in `Authorization` header)	Invalidate tokens

Swap Program (On-Chain)

Program ID:

CCSwaptcDXtfjyRMYBqavqBwiW162yXFAJrXN53UuENC

The swap program is an Anchor-based Solana smart contract. Trades follow this lifecycle:

Open → Approved → Executed → Settled → (Closed)
         ↑            ↑
    cancel_trade  cancel_trade

Instructions:

Instruction	Description
`create_trade`	Initialize trade between two wallets
`approve_trade`	Signal readiness (both parties must approve)
`execute_trade`	Commit to execution (both parties must execute)
`cancel_trade`	Abort open or approved trades
`execute_nft_batch`	Transfer standard NFTs into/out of escrow
`execute_pnft_batch`	Transfer programmable NFTs
`execute_cnft_batch`	Transfer compressed NFTs
`execute_token_batch`	Transfer SPL tokens
`mark_trade_settled`	Backend confirmation of completion
`close_trade`	Final cleanup and rent refund

Marketplace On-Chain Details

Account Structure

Account	Purpose
Market	Singleton PDA — config (admin keys, fees, treasury, paused status)
Listing	Sale info indexed by asset ID + seller, with delegation authority
Offer	Buyer offer details with independent escrow backing
UserEscrow	Per-user USDC deposit tracking for offer collateral

Fee Structure

Platform fee: 200 basis points (2%). Configurable 0–200 bps.

fee = floor(price * platform_fee_bps / 10000)

Uses u128 intermediate precision to prevent overflow.

Security Properties

Non-custodial listings — NFTs remain in seller wallets using delegation, not escrow transfers
Frontrun prevention —
```
expected_price
```
parameters validate on-chain prices match expectations
Self-trade blocking — enforced
```
seller != buyer
```
validation
PDA determinism — fixed seed schemes prevent unauthorized account substitution
Broadcast allow-list — transactions validated against approved program IDs before submission

Error Handling

Success is any 2xx — accept
200
AND
201
. Several marketplace write endpoints (

/marketplace/buy

/marketplace/broadcast

) return

on success. Never gate on

status == 200

; check for a 2xx status plus

success: true

/ a

signature

/ a transaction body.

All APIs return errors in a standard shape:

json

{"statusCode": 400, "message": "human-readable error", "error": "Bad Request"}

Status	Meaning
`400`	Invalid input, on-chain failure, price mismatch, insufficient escrow, signing failure
`401`	Invalid or expired token
`403`	Access denied, program ID outside broadcast allow-list
`404`	Card, NFT, listing, offer, or address not found
`409`	Conflict (already listed, owner changed, wallet linked to Privy account)
`429`	Rate limit exceeded
`500`	Machine empty, too many packs open, or processing error

Safety Notes

Marketplace prices are in whole USDC.
```
"price": 25
```
means $25.00 USDC.
Buy/broadcast succeed with HTTP
201
— accept any 2xx, parse the body which may be raw base64 (not JSON), and verify the result on Solana RPC (
```
getSignatureStatuses
```
), not via a marketplace refetch. See the End-to-End Buy Recipe.
Metaplex Core (
nftStandard: "core"
) is common — omit
```
tokenStandard
```
for those; only send
```
"Pnft"
```
/
```
"Cnft"
```
when the asset really is one.
Starchild wallet signing returns
signed_transaction
(snake_case) — read that (or the camelCase fallback) before broadcasting.
Gacha
refundAmount
is in USDC lamports. 42,500,000 = $42.50 USDC (1 USDC = 1,000,000 lamports).
Gacha buyback window is 72 hours. After that, the NFT cannot be sold back to the machine.
Buyback refund is a per-machine percentage of insured/market value (not the purchase price). The rate is exposed as
```
instantBuyback
```
in
```
GET /api/machines
```
(e.g.
```
85
```
= 85%); don't assume a fixed global rate. Use
```
GET /api/buyback/available?wallet=…&nft=…
```
to get the exact refund
```
amount
```
before building a buyback tx (USDC base units, already adjusted for the machine's buyback % and capped at 40,000 USDC).
Non-custodial listings — NFTs stay in seller wallets via delegation. If a seller transfers an NFT without canceling the listing, the listing becomes invalid. Backend auto-cancellation is not guaranteed.
Escrow must be pre-funded for offer updates —
```
update-offer
```
does NOT transfer additional USDC; the escrow must already contain the full new amount.
cNFT accept-offer may require two transactions — if the cNFT is currently listed, the API returns a cancel-listing tx that must be signed first.
Shipping creates real physical shipments. Always confirm address and NFT selection with the user before calling
```
/redeem/prepare
```
.
Signed transactions are irreversible. Verify NFT address, price, and wallet before broadcasting.
VRF rolls are final. Once a pack is opened, the result cannot be changed or re-rolled.
Track B (SIWS) is crypto-only. No card payment support. Wallets already linked to Privy accounts will get
```
409 Conflict
```
.
userHasSol: false
— use this flag when the user's wallet lacks SOL for transaction fees; the backend will pay gas. Also use it to recover from
```
INSUFFICIENT_FUNDS_RETRYABLE
```
broadcast errors.

Known Limitations

Marketplace uses delegation, not escrow — if a seller transfers their NFT elsewhere without canceling, the listing breaks silently. Always check listing validity before buying.
Field names differ across endpoints — listing uses
```
nftAddress
```
, cancel-listing uses
```
tokenMint
```
, update-listing uses
```
tokenMint
```
+
```
newPrice
```
+
```
coin
```
. Always check the exact field names per endpoint above.
Gacha
packType
codes are machine-specific (e.g.,
```
pokemon_50
```
,
```
pokemon_250
```
). Use
```
GET /api/machines
```
to discover available pack types and current pricing.
No keyword search for gacha NFTs — use
```
GET /api/getNfts
```
with
```
code
```
and
```
rarity
```
filters, or browse via
```
GET /api/machines
```
.
Swap is on-chain only — no REST API wrapper; interact via Solana transactions against the Anchor program IDL.
Access tokens expire in 15 minutes (Track B / SIWS) — implement refresh token rotation for long sessions.
eBay Bidder has no public API documentation — it's a consumer-facing tool at
```
https://bid.collectorcrypt.com
```
.
Launchpads are admin-managed drop pages — no public API for creating or configuring them.
Browse listings cache — unauthenticated GET requests are cached for 5 seconds.

collectorcrypt

NPX Install

Tags

SKILL.md Content

CollectorCrypt API

Key Concepts

Product Suite

Solana Programs

NFT Types Supported

Currency

Transaction Pattern (Marketplace & Shipping)

Gacha Rarity Tiers

VRF (Verifiable Random Function)

How to Call

Gacha API — No API Key (the key does not exist)

Marketplace API — No Auth for Reads

Shipping API — Two Auth Tracks

Intent Routing

Marketplace

List an NFT — POST /marketplace/list

Cancel a Listing — POST /marketplace/cancel-listing

Update a Listing Price — POST /marketplace/update-listing

Buy an NFT — POST /marketplace/buy

End-to-End Buy Recipe (tested live)

Make an Offer — POST /marketplace/make-offer

Cancel an Offer — POST /marketplace/cancel-offer

Update an Offer — POST /marketplace/update-offer

Accept an Offer — POST /marketplace/accept-offer

Browse Listings — GET /marketplace

Broadcast a Transaction — POST /marketplace/broadcast

Gacha Machine

Gacha Response Shapes

Shipping / Vault Redemption

Shipping Address Management

Shipping Rates

Redeem/Prepare Response Shape

Auth (SIWS — Sign-In With Solana)

Swap Program (On-Chain)

Marketplace On-Chain Details

Account Structure

Fee Structure

Security Properties

Error Handling

Safety Notes

Known Limitations

List an NFT —
`POST /marketplace/list`

Cancel a Listing —
`POST /marketplace/cancel-listing`

Update a Listing Price —
`POST /marketplace/update-listing`

Buy an NFT —
`POST /marketplace/buy`

Make an Offer —
`POST /marketplace/make-offer`

Cancel an Offer —
`POST /marketplace/cancel-offer`

Update an Offer —
`POST /marketplace/update-offer`

Accept an Offer —
`POST /marketplace/accept-offer`

Browse Listings —
`GET /marketplace`

Broadcast a Transaction —
`POST /marketplace/broadcast`