SP3ND
API contract v2

Partner API

Build carts from product links or live Collector Crypt cards, treat reviewed quotes as a normal async state, and take USDC payment on orders at SP3ND prices.

Apply for access
ContractServer-authoritative totals
ReviewAsynchronous and resumable
Payment gatepayment_ready only

Authentication

Keep credentials, and every Partner API call, on your server.

Request headers
X-API-Key: sp3nd_...
X-API-Secret: sp3nd_sec_...

SP3ND resolves product facts and owns the final price, shipping, tax, fees, total, currency, payment memo and recipient. Values you send are never payment authority.

Base URL
https://us-central1-sp3nddotshop-prod.cloudfunctions.net
schema_version
The response envelope is version 2 and additive; existing fields stay available.
order_schema_version
New orders use 2. Older stored orders can report 1 inside the version 2 envelope.
payment_ready
The only supported signal that payment can begin.

Order lifecycle

A review state is a successful order, not an API failure.

  1. Cart
  2. Order
  3. Team review, if needed
  4. payment_ready: true
  5. Paid
{
  "status": "Created",
  "checkout_role": "direct_payment",
  "pricing_status": "ready_for_payment",
  "requires_manual_quote": false,
  "payment_ready": true
}
checkout_role
Exactly direct_payment or manual_review. Stored legacy roles are normalized.
pricing_status
awaiting_team_quote, shipping_selection_required or ready_for_payment. Informational only.
payment_ready
The sole payment gate. No role, status, quote or total authorizes payment by itself.

If any item in a mixed cart needs review, the whole cart becomes one Awaiting Review order. It isn't split into child orders.

Create a server-priced cart

Send product URLs or one Collector Crypt asset. SP3ND resolves the product and every commerce value.

createPartnerCart.js
const response = await fetch(
  'https://us-central1-sp3nddotshop-prod.cloudfunctions.net/createPartnerCart',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.SP3ND_API_KEY,
      'X-API-Secret': process.env.SP3ND_API_SECRET
    },
    body: JSON.stringify({
      ship_to_country: 'United States',
      ship_to_postal_code: '10007',
      items: [{
        product_url: 'https://www.ebay.com/itm/123456789',
        quantity: 1
      }]
    })
  }
);

Physical carts expire after 30 minutes. A complete shipping_address can replace the country and postal code shortcut. Older clients can still send extra item metadata, but titles and prices you send aren't treated as verified.

Search and quote Collector Crypt cards

Discovery is live, authenticated and read-only. Pricing comes from the cart, not the search. Normal authenticated, approved Partner credentials allow search, quotes, real card orders, and USDC payment without a separate opt-in. getAgentStatus.agent.collector_crypt_enabled is a derived discovery capability, always true for approved Partners, not a stored setting.

searchCollectorCryptCards
GET https://us-central1-sp3nddotshop-prod.cloudfunctions.net/searchCollectorCryptCards?q=charizard%20psa%2010&limit=20
X-API-Key: <api-key>
X-API-Secret: <api-secret>

// response
{
  "success": true,
  "schema_version": 2,
  "provider": "collectorcrypt",
  "currency": "USDC",
  "items": [{
    "pricing_source": "collectorcrypt_live_listing",
    "product_type": "tokenized_collectible",
    "fulfillment_type": "wallet_delivery",
    "card_id": "<provider-card-id>",
    "nft_address": "<asset-address>",
    "product_url": "https://collectorcrypt.com/assets/solana/<asset-address>",
    "back_image_url": "https://<provider-image-host>/back.jpg",
    "price": 125,
    "listing_price_usdc": 125,
    "currency": "USDC",
    "card_type": "Pokemon",
    "grading_id": "<provider-grading-id>",
    "insured_value_usd": 150,
    "listed_at": "2026-09-01T00:00:00.000Z",
    "listing_updated_at": "2026-09-01T00:01:00.000Z",
    "max_quantity": 1
  }],
  "next_cursor": null,
  "total": 1,
  "marketplace_total": 2400,
  "total_pages": 1,
  "category_counts": { "Pokemon": 1800, "Sports": 600 }
}
q
Optional, up to 200 characters. Searches card and item names, or looks up an exact NFT address or grading ID. Leave it out to browse.
limit
Optional, 1 to 100. Defaults to 20.
cursor
Optional opaque next_cursor, returned unchanged; nonblank, at most 2,048 characters, with no control characters. It takes precedence over page.
page
Optional integer, 1 to 10,000, when no cursor is sent.

Results include only native Solana Collector Crypt V2 buy-now listings priced in USDC with a supported token_standard (Pnft, Cnft, StandardNft, or CoreNft) and an exact cent-denominated price. listing_price_usdc mirrors generic price; insured value and listing timestamps are catalog metadata. Upstream totals, page totals, and category counts are computed before SP3ND filters ineligible rows, so they may exceed items.length. Search doesn't reserve a listing. Create a five-minute, one-card cart from the asset URL or { provider: "collectorcrypt", nft_address, quantity: 1 }, with no shipping fields and no Amazon or eBay items. An optional top-level cart user_wallet must be a valid on-curve Solana address. SP3ND stores it and uses it when the order request omits its own user_wallet; final buyer/recipient equality is enforced at order creation. An invalid cart wallet returns USER_WALLET_INVALID.

Storefronts

A supported URL and delivery to a destination are separate checks.

Amazon
Storefronts
amazon.comamazon.co.ukamazon.caamazon.deamazon.framazon.esamazon.itamazon.nlamazon.com.beamazon.plamazon.seamazon.com.bramazon.com.mxamazon.com.auamazon.inamazon.co.jpamazon.sgamazon.aeamazon.saamazon.egamazon.com.tramazon.co.zaamazon.ieamazon.beamazon.cn
Share links
a.coamzn.toamzn.euamzn.asia
eBay
Storefronts
ebay.comebay.caebay.co.ukebay.deebay.atebay.frebay.itebay.esebay.ieebay.nlebay.beebay.chebay.plebay.com.auebay.com.hkebay.com.myebay.phebay.com.sgebay.inebay.cnebay.com.twebay.vnebay.co.th
Share links
ebay.io/m/<code>
Collector Crypt
Canonical URL only
collectorcrypt.com/assets/solana/<asset-address>
Native Solana V2 buy-now listings in USDC. Delivered to asset_recipient_wallet; no shipping address.

Storefront support does not guarantee that a particular seller will ship a listing to every destination. SP3ND checks the listing using the final country and postal code. A cross-storefront order is valid only when SP3ND receives a verified ship-to-home quote for that address. Prefer the recipient country’s storefront when one is available. Share links are expanded and revalidated server-side; SP3ND stores the canonical marketplace product URL.

EBAY_UNDELIVERABLE with undeliverable_reason: "local_pickup_only" is a hard listing restriction. EBAY_QUOTE_UNAVAILABLE is temporary or inconclusive and may be retried. Taiwan storefront URLs are recognized, but the listing still needs a verified quote to the buyer’s exact Taiwan address.

Create an idempotent order

One stable idempotency key stands for one checkout attempt.

const response = await fetch(
  'https://us-central1-sp3nddotshop-prod.cloudfunctions.net/createPartnerOrder',
  {
    method: 'POST',
    headers: {
      ...authHeaders,
      'Idempotency-Key': checkoutAttemptId
    },
    body: JSON.stringify({
      cart_id: cart.cart_id,
      customer_email: 'buyer@example.com',
      shipping_address: {
        name: 'Ada Buyer',
        recipient: 'Ada Buyer',
        address1: '123 Main Street',
        address2: 'Suite 4',
        city: 'New York',
        state: 'NY',
        postalCode: '10007',
        country: 'United States',
        phone: '+12125550123'
      }
    })
  }
);

For a Collector Crypt cart, leave out shipping_address and send the same on-curve wallet as user_wallet and asset_recipient_wallet. Gifting isn't supported; a mismatch returns ASSET_RECIPIENT_WALLET_MISMATCH. The wallet is frozen once payment preparation begins.

Idempotency-Key
Preferred header. idempotency_key in the body also works.
Same key, same request
Returns the original order, possibly with idempotent_replay: true.
Same key, changed request
Returns 409 IDEMPOTENCY_CONFLICT.

Review quotes and shipping

Poll the order, show the current choices, and send back an option ID unchanged.

getPartnerOrder · selectPartnerOrderShippingOption
GET https://us-central1-sp3nddotshop-prod.cloudfunctions.net/getPartnerOrder?order_id=abc123

POST https://us-central1-sp3nddotshop-prod.cloudfunctions.net/selectPartnerOrderShippingOption
{
  "order_id": "abc123",
  "shipping_option_id": "standard"
}
quote_revision
Identifies the current team quote.
quote_expires_at
After this, fetch a new quote before continuing.
shipping_options
Each has shipping_option_id, label, shipping, tax and total amounts and currency. Description and estimated delivery are optional.
selected_shipping_option_id
The chosen option, or null while a choice is required.
selected_shipping_option
The current choice, in the same shape as an option. selected_manual_shipping_option is a deprecated alias.

Quote revision and expiry are enforced on selection. On a conflict, refresh the order and show the current options. Never calculate or patch the total client-side.

Pay a ready order

Standard Partner API. If you were issued Partner API credentials for a normal server integration, use createPartnerTransaction. Do not use payAgentOrder. For shipped products, call the standard endpoint once, then build and submit the on-chain payment in your own wallet integration using only authoritative SP3ND values. Collector Crypt is the explicit exception below.

Never call createPartnerTransaction and then payAgentOrder for the same checkout. They are two different payment paths and must not share client-side settlement state.

createPartnerTransaction
POST https://us-central1-sp3nddotshop-prod.cloudfunctions.net/createPartnerTransaction
Content-Type: application/json
X-API-Key: <api-key>
X-API-Secret: <api-secret>

{
  "order_id": "abc123",
  "sender_address": "<buyer-solana-wallet>"
}

// 201 response: use these exact server-derived fields
{
  "success": true,
  "status": "pending",
  "order_id": "abc123",
  "order_number": "ORD-...",
  "amount": 10.81,
  "currency": "USDC",
  "memo": "SP3ND Order: ORD-...",
  "recipient_address": "<sp3nd-treasury>"
}

createPartnerTransaction registers the authoritative payment attempt; it does not submit or sign a wallet transaction for you. Make that authenticated request on your server. Pass only its returned payment instructions to your trusted wallet signer. It rejects real Collector Crypt orders with COLLECTOR_CRYPT_PAYMENT_METHOD_UNSUPPORTED.

Exact Solana USDC transfer
import {
  PublicKey,
  Transaction,
  TransactionInstruction,
} from '@solana/web3.js';
import {
  ASSOCIATED_TOKEN_PROGRAM_ID,
  TOKEN_PROGRAM_ID,
  createTransferCheckedInstruction,
  getAssociatedTokenAddressSync,
} from '@solana/spl-token';

const USDC_MINT = new PublicKey(
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
);
const MEMO_PROGRAM_ID = new PublicKey(
  'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'
);

// 10.81 USDC -> 10_810_000n. Never multiply a JS number by 1e6.
function toUsdcAtomicUnits(decimalAmount) {
  const match = /^(0|[1-9]\d*)(?:\.(\d{1,6}))?$/.exec(
    String(decimalAmount)
  );
  if (!match) throw new Error('Invalid USDC amount from SP3ND');
  const [, whole, fraction = ''] = match;
  return BigInt(whole) * 1_000_000n +
    BigInt(fraction.padEnd(6, '0'));
}

async function signAndBroadcastSp3ndPayment({
  payment,
  buyerPublicKey,
  connection,
  signTransaction,
}) {
  if (payment.status === 'confirmed') return null; // Never pay again.
  if (payment.status !== 'pending' || payment.currency !== 'USDC') {
    throw new Error('SP3ND payment is not payable');
  }

  const recipientOwner = new PublicKey(payment.recipient_address);
  const buyerUsdcAta = getAssociatedTokenAddressSync(
    USDC_MINT, buyerPublicKey, false,
    TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID
  );
  const recipientUsdcAta = getAssociatedTokenAddressSync(
    USDC_MINT, recipientOwner, false,
    TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID
  );
  const { blockhash, lastValidBlockHeight } =
    await connection.getLatestBlockhash('confirmed');

  const transaction = new Transaction({
    feePayer: buyerPublicKey,
    recentBlockhash: blockhash,
  }).add(
    createTransferCheckedInstruction(
      buyerUsdcAta,
      USDC_MINT,
      recipientUsdcAta,
      buyerPublicKey,
      toUsdcAtomicUnits(payment.amount),
      6,
      [],
      TOKEN_PROGRAM_ID
    ),
    new TransactionInstruction({
      programId: MEMO_PROGRAM_ID,
      keys: [],
      data: Buffer.from(payment.memo, 'utf8'),
    })
  );

  const signed = await signTransaction(transaction); // buyer signs
  const signature = await connection.sendRawTransaction(signed.serialize());
  await connection.confirmTransaction(
    { signature, blockhash, lastValidBlockHeight },
    'confirmed'
  );
  return signature;
}
  1. Use the returned amount, currency, memo and recipient unchanged. Convert the amount by padding to six decimals: 10.81 is exactly 10,810,000 atomic units, never a floating-point multiplication.
  2. Treat recipient_address as the treasury owner. Derive both canonical ATAs from the Solana mainnet USDC mint and the standard Token/Associated Token programs.
  3. Fetch a fresh blockhash and build a legacy Transaction with the buyer as fee payer and TransferChecked authority. Add TransferChecked followed by the Memo Program instruction using the exact memo bytes.
  4. Sign and broadcast through the partner’s wallet and Solana RPC. Do not send PAYMENT-SIGNATURE or call a facilitator.
  5. Poll getPartnerOrder until it's Paid. Never send a second payment while confirmation is pending.

HTTP 200 with status: confirmed means the order was already paid and no transaction may be constructed. HTTP 201 with status: pending supplies the one payment above. On 409 or any other non-2xx response, do not broadcast; read the order and follow its lifecycle code.

Advanced legacy agentic-skill appendix and MCP boundary

Use payAgentOrder only if your client intentionally implements SP3ND’s published legacy x402 agentic-skill contract. It is not the next step after createPartnerTransaction, and it is not the MCP payment path. Real Collector Crypt orders are rejected on this surface and use partnerPayment only. Follow the separate published SP3ND agentic skill or contact SP3ND for the current legacy integration contract.

The public SP3ND MCP tools use the same partnerPayment prepare/submit backend as the Collector Crypt Partner API path, but bind it to their own OAuth session and approval ticket. MCP clients stay inside those tools; direct Partner API clients use their server credentials.

For these paths, order_number is optional and validated when sent. Caller-provided amount, currency, memo, and recipient_address are ignored. Payment can begin only when the latest response has payment_ready: true; pricing_status is informational and is never a second payment gate.

ORDER_NOT_PAYMENT_READY means keep the customer in review and poll the order. PAYMENT_SETTLEMENT_IN_PROGRESS also means poll without resubmitting payment. If PAYMENT_SETTLEMENT_UNKNOWN is returned, do not retry: retain the order ID and request manual reconciliation.

Endpoints

Cloud Function names are part of the public contract.

GETsearchCollectorCryptCardsSearch live Collector Crypt USDC cards
POSTcreatePartnerCartCreate a server-priced cart
POSTaddItemToPartnerCart/{cartId}Add one item
PATCHupdateCartItemQuantity/{cartId}/{itemId}Change quantity
DELETEremoveCartItem/{cartId}/{itemId}Remove an item
PATCHupdateCartShippingAddress/{cartId}Change destination and reprice
GETgetPartnerCart/{cartId}Read a cart
POSTcreatePartnerOrderCreate an order
GETgetPartnerOrder?order_id=…Read one order
GETgetPartnerOrdersList orders
GETgetPartnerKpisRead aggregate-only KPIs
POSTselectPartnerOrderShippingOptionChoose reviewed shipping
POSTcreatePartnerTransactionShipped-product payment; rejects cards
POSTpartnerPaymentPrepare or submit exact card payment bytes
POSTpayAgentOrderLegacy agentic-skill clients only

getPartnerOrders lists all orders when status is left out or set to all. It takes limit (1–100, default 50) and offset (0–499), with limit + offset ≤ 500. Optional user_wallet and customer_email filters apply before pagination.

Aggregate reporting

Read your partner KPIs without receiving or storing customer order rows.

getPartnerKpis
GET https://us-central1-sp3nddotshop-prod.cloudfunctions.net/getPartnerKpis?start_date=2026-08-01T00:00:00.000Z&end_date=2026-09-01T00:00:00.000Z

X-API-Key: <api-key>
X-API-Secret: <api-secret>
Range
start_date is inclusive, end_date exclusive, both ISO-8601 with a timezone. Leave both out for the last 30 days. Up to 90 days.
Limit
Scans up to 5,000 orders; beyond that you get 413 KPI_SCAN_LIMIT_EXCEEDED, never partial results.
gross_created
Every non-test order created in the range, including ones later cancelled or refunded.
settled
The only bucket that counts fees and revenue share.

Test orders are excluded. The response separates gross_created from settled volume. gross_created includes every non-test order created in the range, including later cancelled or refunded orders. Fees and revshare are counted only in settled. Current cancelled and refunded buckets report count and gross order value, not actual loss or refund amounts. The status breakdown remains available. No order IDs, items, wallets, emails, addresses, or payment identifiers are returned.

Lifecycle codes

Use the machine-readable code, and refresh state after any quote conflict.

ORDER_NOT_PAYMENT_READYPoll the order; don't submit payment.
ORDER_NOT_PAYABLEStop; this order can't accept payment.
PAYMENT_SETTLEMENT_IN_PROGRESSDon't resubmit payment; poll the order.
PAYMENT_SETTLEMENT_UNKNOWNDon't retry; keep the order ID for manual reconciliation.
IDEMPOTENCY_CONFLICTUse the original payload or a new checkout key.
COLLECTOR_CRYPT_SINGLE_ITEM_REQUIREDCreate a one-card cart and don't mix it with shipped products.
COLLECTOR_CRYPT_QUERY_INVALID / LIMIT_INVALID / CURSOR_INVALID / PAGE_INVALIDFix the discovery input; pass an upstream cursor back unchanged.
USER_WALLET_INVALIDUse a valid on-curve Solana address for the optional cart user_wallet.
COLLECTOR_CRYPT_LISTING_CHANGEDCreate a fresh cart from the current live listing.
COLLECTOR_CRYPT_LISTING_UNAVAILABLEStop checkout; the card is no longer an eligible listing.
COLLECTOR_CRYPT_LISTING_IDENTITY_INVALIDStop; the listing lacks an immutable asset or receipt identity.
COLLECTOR_CRYPT_LISTING_RESERVEDStop; another SP3ND order owns this exact listing.
COLLECTOR_CRYPT_ORDER_CHANGED / RESERVATION_EXPIREDDon't pay; read or rebuild the card order as directed.
COLLECTOR_CRYPT_PAYMENT_METHOD_UNSUPPORTEDUse partnerPayment; both legacy payment endpoints reject real cards.
ASSET_RECIPIENT_WALLET_MISMATCHUse the same wallet for user_wallet and asset_recipient_wallet; gifting isn't available.
PAYER_ADDRESS_INVALID / PAYER_ADDRESS_MISMATCHPrepare with the valid buyer wallet frozen on the order.
ORDER_ID_REQUIRED / ASSET_RECIPIENT_WALLET_REQUIREDSend the opaque order ID and the same valid buyer and delivery wallet.
SIGNED_TRANSACTION_INVALID / SIGNED_TRANSACTION_REJECTEDSubmit only the exact signed serialization returned by prepare.
PAYMENT_NOT_PREPARED / PAYMENT_ATTEMPT_EXISTS / PAYMENT_ATTEMPT_INVALIDRead the current order and attempt; never create a parallel payment.
ORDER_CHANGED / PAYMENT_TOTAL_INVALID / PAYMENT_AMOUNT_INVALIDStop and read the order; don't build replacement payment values.
PAYMENT_SIGNATURE_CONFLICT / PAYMENT_SIGNATURE_REUSEDStop; never attach another signature or reuse one across orders.
COLLECTOR_CRYPT_PRICING_CONFIGURATION_INVALIDStop; SP3ND can't create a card order below provider cost.
TEST_PAYMENT_UNSUPPORTEDDon't send a real wallet payment for a test order.
PAYMENT_TRANSACTION_NEAR_EXPIRYDon't sign; wait past the last valid block height, then prepare again.
PAYMENT_TRANSACTION_FAILED / PAYMENT_TRANSACTION_EXPIREDThe old attempt is terminal and released; prepare fresh bytes.
PAYMENT_STATUS_UNAVAILABLE / PAYMENT_PREFLIGHT_UNAVAILABLEWhen retryable, retry only the exact signed bytes.
PAYMENT_RECONCILIATION_PENDINGKeep the payment locked; retry only the original signed bytes.
QUOTE_EXPIREDFetch the current order and quote.
QUOTE_REVISION_MISMATCHRefresh before selecting shipping.
CART_EXPIREDCreate and price a new cart.
EBAY_UNDELIVERABLEStop for this listing and destination. Local-pickup-only isn't retryable.
EBAY_QUOTE_UNAVAILABLETemporary or inconclusive; retry later.
RATE_LIMITEDBack off before retrying.

Migration checklist

Tick these off as you move to v2.

0 of 11

Need a hand?Email us your partner name, endpoint, timestamp and order_id or cart_id. Never send an API secret or a signed payment.

support@sp3nd.shop