Skip to main content
POST
Create a one-token shipment

Authorizations

Authorization
string
header
required

Your API key (cb_live_…), sent as a bearer token, with the scope nft:orders. Keep it on your servers: never in a browser, app or wallet. Use a separate key per environment. A request from a country on our sanctions list gets a 403 with Access denied, whether or not it has a valid key. See Authentication and keys.

Scopes

nft:orders

Headers

Idempotency-Key
string
required

Your own shipment id, 8-128 characters of A-Za-z0-9_-. Both shipment endpoints share one key space. The same key with a different request (tokens in any order, holder, address, rate, cover_amount) is 422.

Pattern: ^[A-Za-z0-9_-]{8,128}$

Path Parameters

tokenId
string
required

The token's decimal token_id, on either chain family. Keep it as a string or bigint, never a JS number.

Pattern: ^[0-9]{1,78}$

Body

application/json
holder
string
required
address
object
required
rate
object
required

A rate from the estimate. We re-quote it.

max_cost
number
required

The most the holder will pay for shipping, in dollars (the estimate's total).

cover_amount
number | null

Shipping insurance cover in dollars, with at most two decimals, within the range the items allow (a 400 COVER_NOT_ALLOWED gives the range). Leave it out or null for none.

Response

A replay of an earlier request with the same Idempotency-Key (idempotent_replay is true).

quote
object
required

A one-token shipment, named by the token's quote_id. fulfilment is present on reads and webhook events, not on the create response.

payment
object | null
required

A Unifold Payment Intent for exactly the amount due. Open it in your app with client_secret and publishable_key (Unifold's web or React Native SDK), or show deposit_addresses and amount. Paid once at least 99% has arrived. Payments.

idempotent_replay
boolean