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.
payment_ready onlyAuthentication
Keep credentials, and every Partner API call, on your server.
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.
- Cart
- Order
- Team review, if needed
- payment_ready: true
- Paid
{
"status": "Created",
"checkout_role": "direct_payment",
"pricing_status": "ready_for_payment",
"requires_manual_quote": false,
"payment_ready": true
}- checkout_role
- Exactly
direct_paymentormanual_review. Stored legacy roles are normalized. - pricing_status
awaiting_team_quote,shipping_selection_requiredorready_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.
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.
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 overpage. - 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
StorefrontseBay
StorefrontsCollector Crypt
Canonical URL onlyasset_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_keyin 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.
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
nullwhile a choice is required. - selected_shipping_option
- The current choice, in the same shape as an option.
selected_manual_shipping_optionis 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.
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.
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; }
- Use the returned amount, currency, memo and recipient unchanged. Convert the amount by padding to six decimals:
10.81is exactly10,810,000atomic units, never a floating-point multiplication. - Treat
recipient_addressas the treasury owner. Derive both canonical ATAs from the Solana mainnet USDC mint and the standard Token/Associated Token programs. - Fetch a fresh blockhash and build a legacy
Transactionwith the buyer as fee payer andTransferCheckedauthority. AddTransferCheckedfollowed by the Memo Program instruction using the exact memo bytes. - Sign and broadcast through the partner’s wallet and Solana RPC. Do not send
PAYMENT-SIGNATUREor call a facilitator. - Poll
getPartnerOrderuntil it'sPaid. 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.
Collector Crypt: exact prepare/submit flow. Card orders use fulfillment_mode: manual and requires_manual_fulfillment: true. Your approved Partner credentials support search, quotes, real orders, and payment without a separate opt-in. Confirmed USDC payment queues SP3ND’s manual acquisition and wallet-delivery work; it does not automatically buy or transfer a card. Fulfillment records combine confirmed transaction references and operator attestations, plus current asset ownership for delivery. They do not cryptographically prove purchase or asset-transfer causality.
POST https://us-central1-sp3nddotshop-prod.cloudfunctions.net/partnerPayment Content-Type: application/json X-API-Key: <api-key> X-API-Secret: <api-secret> { "action": "prepare", "order_id": "abc123", "payer_address": "<buyer-solana-wallet>" } // 201 new preparation; a safe replay is 200 + idempotent_replay=true { "success": true, "status": "payment_prepared", "idempotent_replay": false, "order_id": "abc123", "order_number": "ORD-...", "amount": 125, "currency": "USDC", "network": "solana-mainnet", "payer_address": "<buyer-solana-wallet>", "recipient_address": "<sp3nd-treasury>", "token_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "token_decimals": 6, "amount_atomic": "125000000", "memo": "SP3ND Order: ORD-...", "unsigned_transaction_base64": "<exact-unsigned-transaction>", "recent_blockhash": "<blockhash>", "last_valid_block_height": 123456789 }
Verify the displayed payment fields, then have exactly payer_address sign the exact returned transaction. Do not rebuild it, change instructions, replace the blockhash, or sign a second authorization. PAYMENT_TRANSACTION_NEAR_EXPIRY means do not sign; wait until the stated blockheight passes before preparing again.
POST https://us-central1-sp3nddotshop-prod.cloudfunctions.net/partnerPayment Content-Type: application/json X-API-Key: <api-key> X-API-Secret: <api-secret> { "action": "submit", "order_id": "abc123", "signed_transaction_base64": "<exact-wallet-signed-transaction>" } // 202 response { "success": true, "status": "verifying_payment", "idempotent_replay": false, "order_id": "abc123", "order_number": "ORD-...", "transaction_signature": "<solana-signature>" }
A prepare retry for the same unchanged order and payer safely returns the same valid bytes. A submit retry must reuse the exact same signed_transaction_base64. After a timeout, network error, or PAYMENT_BROADCAST_UNKNOWN, read the order first and never rebuild, re-sign, or prepare a replacement while the original outcome is unknown. verifying_payment is not Paid.
Paid confirms treasury receipt, not delivery. After SP3ND confirms treasury receipt, Paid still does not mean card delivery. The backend normally queues pending_acquisition; a claim mismatch reports review_required. Pending is not proof that SP3ND’s manual operations team has acquired or transferred the card. A purchase signature is not final delivery. Authorized operations must atomically set the top-level order status to Delivered with that fulfillment evidence; clients use the top-level status as the completion gate and may show asset_transfer_signature when present. A sold or changed listing may require manual handling and a refund.
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.
searchCollectorCryptCardsSearch live Collector Crypt USDC cardscreatePartnerCartCreate a server-priced cartaddItemToPartnerCart/{cartId}Add one itemupdateCartItemQuantity/{cartId}/{itemId}Change quantityremoveCartItem/{cartId}/{itemId}Remove an itemupdateCartShippingAddress/{cartId}Change destination and repricegetPartnerCart/{cartId}Read a cartcreatePartnerOrderCreate an ordergetPartnerOrder?order_id=…Read one ordergetPartnerOrdersList ordersgetPartnerKpisRead aggregate-only KPIsselectPartnerOrderShippingOptionChoose reviewed shippingcreatePartnerTransactionShipped-product payment; rejects cardspartnerPaymentPrepare or submit exact card payment bytespayAgentOrderLegacy agentic-skill clients onlygetPartnerOrders 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.
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_dateis inclusive,end_dateexclusive, 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.No codes match.
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.