Developer documentation

Create a stablecoin payment order

Create USDT / USDC payment orders from your server with signed API requests. Check required fields, receiving network, full payable amount, checkout URL, expiry and callback settings.

POST /api/v1/order/create

Authentication Required

Include X-Bolt-Key, X-Bolt-Timestamp and X-Bolt-Signature. Use a current millisecond timestamp and sign the timestamp together with the exact raw request body.

USDTUSDC

Exact amount matching

Why the returned payment amount may be slightly higher

Launch plan

3 fixed digits

Business Pro

2-6 configurable

The amount is rounded up to the configured matching precision. If a pending order on the same network, currency and receiving wallet already uses that amount, a small increment distinguishes the new order. The payable amount is never below the submitted amount. Free accounts use 3 digits; Pro accounts can choose 2–6. Always use the returned payment.amount.

Matching flow

Create order

1

amount

Your backend sends the settlement amount and BoltUtil returns the payable on-chain amount.

Show checkout

2

payment.amount

Display the exact returned amount, network, and receiving address to the payer.

Reconcile chain

3

Webhook

The monitor matches by network, address, token, amount, and order status before notifying you.

Integration notes

1

Display payment.amount from the create-order response, not the request amount or the original product price.

2

Do not round, truncate, or remove the small decimal offset when showing payment instructions.

3

Changing the offset precision only affects newly created orders, not existing pending orders.

4

Verify the Webhook signature and deduplicate notifications before fulfilling by externalOrderId and confirmed payment status. A payment awaiting confirmation is not payment success.

01. Request Body

JSON Payload
amount
Required
Decimal

Original product or business order amount in the currency specified by currency. Send a string to avoid floating-point precision loss. The payer must pay the returned payment.amount rather than this value.

Basic minimum: 1.00. Also satisfy the minimum configured for the selected network and currency.Precision limit: Up to 6 decimal placesSecurity Risk: Strictly forbid passing amounts calculated on the frontend. Always retrieve values from your backend database.
externalOrderId
Required
String

Your business order ID, used to associate the BoltUtil order. Queries use externalOrderId; the create response returns merchantExternalId, and Webhooks return externalOrderId.

Must be globally unique per merchantSupported: Letters, numbers, underscores (_), hyphens (-)Length limit: 6 - 64 charactersA duplicate ID returns an error rather than the existing order.
network
Required
String

Choose a payment network using one of the uppercase values below. For example, use BASE for Base or ERC20 for Ethereum.

Example value

"network": "BASE"
Allowed values: TRC20, ERC20, BEP20, POLYGON, SOLANA, BASEShow the same network in checkout.
currency
Required
String

Choose the payment currency. Pass only USDT or USDC; specify the network separately in network.

Example value

"currency": "USDC"
Allowed values: USDT, USDC⚠️ TRC20 supports USDT only. Other pairs require an enabled route and a valid receiving wallet.
orderDesc
String

Optional product or business summary for order records. The current checkout does not display this field.

Suggested format: Top-up - [User Account]Maximum length: 255 characters
notifyUrl
URL

Webhook receiver for this order. If omitted, the enabled default address in your merchant dashboard is used.

Must be HTTPSMust be publicly accessibleImmutable: This URL cannot be modified once the order is created.Before creating an order, configure and enable the Webhook and signing secret in your dashboard. This parameter does not replace that configuration.Maximum length: 255 characters
returnUrl
URL

After payment completes or the user chooses to return, checkout redirects the browser to this URL. It is only a navigation destination and does not prove payment success.

Verify payment through the signed Webhook or an order-status queryIf omitted, the default is https://boltutil.com.Maximum length: 255 characters
expiredMinutes
Long

The number of minutes an order remains payable after creation. The free plan is fixed at 30 minutes; Pro members can choose 15-60 minutes.

Configurable range: 15-60 minutesDefault: 30 minutesOnly Pro members can customize this value; the free plan is fixed at 30 minutesFree accounts ignore custom values within the valid range and use 30 minutes. Use time.expireTimestamp as the actual expiry.
metadata
Map

Merchant-defined JSON data. BoltUtil does not modify it and returns it unchanged in the create-order response, order-status response, and Webhook.

Format: standard JSON objectReturned unchanged and never used for payment matchingAt most 10 top-level keys

02. Response Details

application/json
orderToken
BoltUtil order identifier for opening checkout. Merchant API queries use externalOrderId.
merchantExternalId
Corresponds to the externalOrderId in the request.
status
PENDING after successful creation. See the order-status documentation for later payment and callback states.
Check Order Status →
checkoutUrl
The exclusive checkout payment link.
returnUrl
Checkout return address. Defaults to https://boltutil.com if omitted.
metadata
The custom passthrough data object.

data.payment { ... }

address
Merchant receiving wallet used by this order. Multiple orders may share this address; no new address is generated per order.
amount
Exact payable amount, returned as a string. Display it in full without rounding or truncating.
rawAmount
Amount in the smallest token unit, returned as an integer string: payment.amount × 10^payment.decimal. For decimal = 6, one token equals 1,000,000 smallest units.
currency
Currency symbol.
network
Network identifier.
qrData
Address string for generating a payment QR code. It does not contain amount, currency or network. Display payment.amount, currency and network separately.
decimal
On-chain precision of the selected token on this network, used to convert rawAmount. It is not the order amount matching precision.

data.time { ... }

expireTimestamp
In data.time: order expiry as a Unix millisecond timestamp.
serverTimestamp
In data.time: server time when the response was generated, as a Unix millisecond timestamp.

Common errors

These are common cases. Use the actual HTTP status and response code/message to diagnose failures. An error response is not a payment result.

  • 401: Check the API Key, raw-body signature and current millisecond timestamp (within 5 minutes of the server clock).
  • 400: externalOrderId already exists. Query the original order instead of creating a duplicate business order.
  • 400: Check required parameters, available network/asset, receiving wallet and enabled Webhook configuration.
  • 429: Request rate limit or free daily order-creation quota reached. Check the business error code and message.
create / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"amount":"25.00","currency":"USDT","network":"TRC20","externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/create" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

Addresses, transaction hashes and orders are examples. Replace them with your own test data.

Base URL

PROD
https://api.boltutil.com