Partner API

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

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
      }]
    })
  }
);

Carts expire after 30 minutes. A complete `shipping_address` can replace the country/postal shortcut. Legacy clients can send extra item metadata, but caller-supplied titles and prices are not treated as verified data.

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'
      }
    })
  }
);

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 and expiry are enforced on selection. If the server returns a conflict, refresh the order and show the current options. Never calculate or patch the total client-side.

Standard Partner API flow

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.

Exact Solana USDC construction

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 decimal amount by padding to six places: `10.81` becomes 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 SP3ND confirms `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.

For both 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.

To list all orders, omit `status` or use `status=all`. The plural `addItemsToPartnerCart` endpoint is not supported in v2.