# StableShipping API

StableShipping buys US domestic shipping labels through Shippo. Supported payment is x402 on Base only.

## Flow

1. POST /api/quote with SIWX to validate US sender/recipient addresses, create a Shippo shipment, and return available rates.
2. Choose one returned rate by `rate_id`.
3. POST /api/labels with x402 to buy the selected label. The price is the Shippo rate amount plus the fixed StableShipping service fee.
4. GET /api/labels or GET /api/labels/{labelId} with SIWX to retrieve labels previously purchased by the signing wallet.
5. GET /api/track/{labelId} with SIWX to refresh tracking for one purchased label.

## Important Behavior

StableShipping MVP supports US domestic shipments only. Both `address_from.country` and `address_to.country` must be `US`. International shipments and customs declarations are not supported yet.

Use inches and pounds or ounces for parcels. The API accepts one parcel per shipment in MVP.

Always call POST /api/quote before buying a label. POST /api/labels accepts a Shippo `rate_id`, re-fetches the rate before payment, validates the final total against the configured maximum, and charges dynamically.

POST /api/labels requires `client_request_id` for idempotency. Reuse the same value only when retrying the same intended label purchase. A reused ID for another wallet or rate returns a conflict.

Shippo label URLs can expire. Store returned tracking information and use GET /api/labels/{labelId} to retrieve the latest stored label metadata.