API Documentation

Checks deliverability and returns the standardized form of an address. The body is a single address object.

curl -X POST https://www.cryptopostage.xyz/api/v1/verify-address \
  -H "Authorization: Bearer cp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe", "street1": "456 Oak Ave", "city": "Los Angeles",
    "state": "CA", "zip": "90001", "country": "US"
  }'

Response: { valid, normalized, issues }.

Returns available services with customer prices (postage + service fee) in USD cents. Optional carriers array (e.g. ["USPS"]) restricts results; customs is required for international shipments (see below). Weight is in ounces, dimensions in inches. For carrier flat-rate packaging, set parcel.predefinedPackage (e.g. FlatRateEnvelope) and omit dimensions — the same codes as the CSV guide.

curl -X POST https://www.cryptopostage.xyz/api/v1/rates \
  -H "Authorization: Bearer cp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAddress": {
      "name": "John Smith", "street1": "123 Main St", "city": "New York",
      "state": "NY", "zip": "10001", "country": "US"
    },
    "toAddress": {
      "name": "Jane Doe", "street1": "456 Oak Ave", "city": "Los Angeles",
      "state": "CA", "zip": "90001", "country": "US"
    },
    "parcel": { "weightOz": 16, "lengthIn": 10, "widthIn": 8, "heightIn": 4 }
  }'

{
  "rates": [
    {
      "carrier": "USPS",
      "service": "Priority",
      "service_name": "USPS Priority Mail",
      "amount_usd_cents": 899,
      "estimated_delivery_days": 2,
      "international": false
    },
    {
      "carrier": "USPS",
      "service": "GroundAdvantage",
      "service_name": "USPS Ground Advantage",
      "amount_usd_cents": 649,
      "estimated_delivery_days": 3,
      "international": false
    }
  ]
}

Note: UPS, FedEx, and DHL require a funded Adjustment Reserve on your account before purchase.

Buys a label using your credit balance. Send the same shipment fields as /rates plus carrier and service (the service code from the rates response). The price is re-quoted server-side at purchase time; your balance is debited the exact live price. Returns 402 when the balance can't cover the label.

curl -X POST https://www.cryptopostage.xyz/api/v1/purchase \
  -H "Authorization: Bearer cp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAddress": { ...same as rates... },
    "toAddress": { ...same as rates... },
    "parcel": { "weightOz": 16, "lengthIn": 10, "widthIn": 8, "heightIn": 4 },
    "carrier": "USPS",
    "service": "Priority"
  }'

{
  "order_id": "CP-A1B2C3D4E5",
  "type": "SHIPPING",
  "status": "COMPLETED",
  "total_usd_cents": 899,
  "credit_applied_cents": 899,
  "created_at": "2026-09-02T18:00:00.000Z",
  "shipments": [
    {
      "id": "...",
      "status": "LABEL_READY",
      "carrier": "USPS",
      "service": "Priority",
      "tracking_number": "9400100000000000000000",
      "tracking_url": "https://tools.usps.com/...",
      "label_url": "https://www.cryptopostage.xyz/api/labels/download?..."
    }
  ],
  "credit_balance_usd_cents": 4101
}

For international shipments, include a customs declaration and phone numbers for both addresses:

"customs": {
  "contentsType": "merchandise",
  "signer": "John Smith",
  "certify": true,
  "customsItems": [
    {
      "description": "Cotton T-shirt",
      "quantity": 2,
      "valueUsdCents": 4000,
      "weightOz": 12,
      "hsTariffNumber": "6109.10",
      "originCountry": "US"
    }
  ]
}

The label is normally generated in the same request (status: "COMPLETED", label_url set). If generation is still in progress or held for review, poll GET /api/v1/orders/{order_id} until the shipment reaches LABEL_READY. Label download links are signed and expire; fetch a fresh one from the order endpoint any time.

Lists your orders, newest first. Query params: limit (1–100, default 20) and cursor (from next_cursor in the previous page).

Returns one order with shipments, tracking, and fresh signed label URLs. Accepts the public order id (CP-…). For unpaid top-up orders the response includes the active payment details.

Returns balance_usd_cents and the last 20 credit events (top-ups, purchases, adjustments).

Creates a crypto payment for the requested USD amount ($5–$10,000). Send the exact amount_crypto to the returned address before it expires; the balance is credited automatically once the payment confirms on-chain.

curl -X POST https://www.cryptopostage.xyz/api/v1/credits/topup \
  -H "Authorization: Bearer cp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_usd_cents": 5000, "coin": "BTC" }'

{
  "order_id": "CP-F6G7H8I9J0",
  "status": "awaiting_payment",
  "amount_usd_cents": 5000,
  "coin": "BTC",
  "payment": {
    "address": "bc1q...",
    "amount_crypto": "0.00043210",
    "payment_uri": "bitcoin:bc1q...?amount=0.00043210",
    "expires_at": "2026-09-02T18:20:00.000Z"
  }
}