Payments API

Greg

We’ve expanded the Thirdweb API with three new endpoints that make it easier than ever to swap, send, and execute payments in just a few calls. Whether you’re moving tokens across chains, building custom checkout flows, or resuming a previously prepared payment, these new endpoints give you full control over the payment lifecycle — all with the same developer-friendly API.

Instantly swap between tokens and across chains using any thirdweb wallet via POST /v1/payments/swap. Use the exact parameter to specify whether your amount is the input (pay) or output (receive) side.

curl -sS -X POST "https://api.thirdweb.com/v1/payments/swap" \
  -H "Content-Type: application/json" \
  -H "x-secret-key: <YOUR_SECRET_KEY>" \
  -d '{
    "from": "0xYOUR_WALLET",
    "exact": "input",                 
    "tokenIn":  { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "chainId": 42161, "amount": "1000000" },
    "tokenOut": { "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "chainId": 42161, "minAmount": "990000" }
  }'

API Reference →

Create an end-to-end payment that can bridge and/or swap under the hood with POST /v1/payments. Perfect for P2P transfers, checkouts, and payouts when you want a single call that returns the prepared steps to execute. Supports metadata and webhooks.

curl -sS -X POST "https://api.thirdweb.com/v1/payments" \
  -H "Content-Type: application/json" \
  -H "x-secret-key: <YOUR_SECRET_KEY>" \
  -d '{
    "name": "Course",
    "description": "The complete JS course",
    "imageUrl": "https://example.com/course.png",
    "recipient": "0xMERCHANT_WALLET",
    "token": { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "chainId": 42161, "amount": "1000000" }
  }'

API Reference →

Submit a previously created payment with POST /v1/payments/{id}. Use this to continue processing a payment you created earlier (for example after client-side signing/approval), while preserving the same payment ID for tracking and webhooks.

curl -sS -X POST "https://api.thirdweb.com/v1/payments/<ID>" \
  -H "Content-Type: application/json" \
  -H "x-secret-key: <YOUR_SECRET_KEY>" \
  -d '{ "from": "0xBUYER_WALLET" }'

API Reference →