Overview
The Utexo Mint API is a network-agnostic REST interface for cross-network asset transfers. Clients must discover the networks currently connected to an environment withGET /networks instead of hardcoding network availability.
USDT0 settles natively on Arbitrum, which acts as the hub; Ethereum, Polygon PoS, Plasma and Tron reach that hub through USDT0 / LayerZero and the Utexo entrypoint contracts.
Base URL:
https://gateway.mint.utexo.com/api/v0All paths in this reference are relative to the base URL. Contact the Utexo team for access to the test environment before launch.Interactive API docs: https://gateway.mint.utexo.com/api/v0/docs/X-API-Key header or a signed-in session cookie (see Authentication).
Transfer Flows
The Mint moves USDT in two directions: lock and mint (USDT0 on EVM → USDT on Bitcoin) and burn and unlock (USDT on Bitcoin → USDT0 on EVM).RGB network ID: take the RGB-side network from
GET /networks. The Utexo RGB network ID is 827166. The RGB wallet must support the BFA asset schema; see RGB wallet requirements.Lock and mint: EVM → RGB
1
Discover networks and tokens
GET /networks — list the connected networks and take the id of the source network and of the RGB network.GET /networks/{network-id}/supported-tokens — take the token id on each side. USDT is the only token bridged today.2
Estimate the mint
GET /mint-burn/estimate/{senderNetworkId}/{recipientNetworkId}/{tokenId}/{amount} — the amount minted on Bitcoin for a gross deposit, and the bridge commission.3
Create an RGB invoice
The recipient’s RGB wallet creates an invoice for the USDT asset.
4
Prepare the mint
POST /mint/op-id - submit the invoice, the gross deposit, the source network and the token ID. The response contains the opId, the settlementData to pass to the deposit, and ttlSeconds. If the source network uses an entrypoint contract, the response also contains an entrypoint object.5
Lock USDT0
Before
ttlSeconds runs out, the user calls fundsIn() on the Arbitrum bridge contract with depositAmount and passes settlementData verbatim as the settlementData argument. On a network that uses an entrypoint contract, the user calls that contract with the returned depositParams instead. This step happens client-side; the API does not broadcast the transaction.6
Track the mint
GET /lock/{opId}/status - poll until the status is completed or expired.Burn and unlock: RGB → EVM
1
Estimate the release
GET /mint-burn/estimate/{senderNetworkId}/{recipientNetworkId}/{tokenId}/{amount} — the USDT0 released for a burn of amount, and the bridge commission.2
Check the release capacity
GET /unlock/capacity/{srcNetworkId}/{networkId}/{tokenId} — read available. A burn cannot be undone, so do not burn more than available.3
Burn USDT on Bitcoin
Burn the amount in the RGB wallet and commit the payout destination: the burn reason is the V1 burn destination hash, on every payout network, and you keep the record for
/unlock (see Burn destination). Then export the burn consignment from the wallet and base64-encode the raw bytes.4
Submit the burn consignment
Optionally,
POST /unlock/verify - dry-run the checks /unlock makes before it claims the burn.POST /unlock - send the base64-encoded consignment, plus burnDestination for a V1 burn. Submit it right after the burn: if the burn is not final on Bitcoin yet, the response is confirming and the bridge sends the release itself once it is.5
Confirm the release
The response contains the
status, the evmTxHash of the submitted release (empty while confirming), the recipient read from the burn, and the operationId under which the transfer history lists the burn. The release confirms on the EVM network asynchronously.Authentication
API key or session
Every endpoint in this reference needs one of:- API key: the
X-API-Keyheader. Send exactly one key; two headers return400. - Session: the customer session cookie set by signing in to the Utexo web app. Browser requests other than
GETalso needX-Requested-With: XMLHttpRequestand a trusted origin.
401.
The API key is self-service. Sign in, complete KYC or KYB, and call POST /users/me/api-key from the signed-in session. The response (201) contains apiKey and createdAt; the raw key is returned only this once. GET /users/me/api-key returns only createdAt, and DELETE /users/me/api-key revokes the key. Keep the key on a trusted backend: do not embed it in a browser app or an untrusted wallet.
Verification and the mint limit
An account without approved KYC or KYB can mint only up to a cumulative limit set by Utexo, which can change: the new gross deposit plus its completed and active mint deposits must stay within it. Above it,GET /mint-burn/estimate (for a mint) and POST /mint/op-id return 403 with code 9. Burns do not count against the limit. GET /users/me (session only) shows kycStatus, kybStatus and the allowance in mintBurnLimit (max, used, reserved, free, unlimited).
Signature authentication
GET /transfers/history/{signature-hex}/{pub-key-hex} also authenticates the wallet, on top of the API key or session. The wallet signs the fixed message Bridge Authentication Proof and passes the signature and its public key or address in the path:
Verification depends on the network type:
- EVM and Tron: the public key is recovered from the signature, converted to an address, and compared against
pub-key-hex. - RGB: authentication is handled inside the RGB network; no signature check happens at this layer.
Endpoints
Networks
GET /networks — List Connected Networks
Returns all connected networks. Optionally filter by token, source network, or name.
Query Parameters
Response
200 — Array of Network objects
GET /networks/{network-id}/supported-tokens — List Supported Tokens
Returns a paginated list of tokens supported on a given network. If token-id is provided as a query parameter, returns a single Token object instead of a paginated response.
Path Parameters
Query Parameters
Response
200 — SupportedTokensResponse
GET /networks/{network-id}/balance/{token-id}/{user-address} — Get User Token Balance
Returns the token balance for a specific user address on a given network.
Path Parameters
Response
200 — string
Balance as a human-readable decimal string in token units (e.g., "100.50").
Mint and burn
GET /mint-burn/estimate/{senderNetworkId}/{recipientNetworkId}/{tokenId}/{amount} — Estimate a Mint or Burn
Quotes what a mint or a burn receives and what the bridge charges. The direction follows from which side is the RGB network. Requires authentication.
Path Parameters
Query Parameters
Response
200
amount = receiveAmount + totalTokenFee on every route.
The amounts above are an example. Fees are set per route and change over time, so always read them from the estimate.
Error Responses
POST /mint/op-id — Prepare a Mint
Prepares the RGB side of a lock-and-mint transfer and returns the data the deposit must carry. It does not move tokens or submit the EVM transaction. Requires authentication. For an account without KYC or KYB, the gross deposit counts against the mint limit.
Request Body
Response
200
The
fundsIn must be included in a block before ttlSeconds runs out. Sending the same request again for a prepared mint that is not paid yet resumes it; a retry never renews the original deadline.
Error Responses
GET /lock/{opId}/status — Get Mint Status
Returns the state of a prepared mint. Poll it after the deposit is submitted. Requires authentication. Returns 404 for an unknown opId.
Response 200
evmTxHash is the detected deposit transaction on the EVM network. It is omitted until the deposit is detected.
GET /unlock/capacity/{srcNetworkId}/{networkId}/{tokenId} — Get Release Capacity
Returns how much can be released right now for a burn. Call it before you burn. Requires authentication.
Path Parameters
Response
200
POST /unlock — Release After a Burn
Validates a burn consignment, gets the release signatures and submits the EVM release. The amount and the payout destination are read from the burn itself; the request cannot change them. Requires authentication. Burns do not count against the mint limit.
Submit right after the burn. The signer enclaves require 6 Bitcoin confirmations of the burn before they sign; if the burn is not final yet, the bridge accepts it as confirming and sends the release itself once it is.
Request Body
Response
200
A burn whose release does not go out within 24 hours (for example, a replaced or dropped burn transaction) shows as
FAILED in the history and can be unlocked again.
Error Responses
Burn destination
A burn commits its payout target in the 32-byte burn reason:hash_v1 of a V1 burn destination record. The bridge releases it with a direct fundsOut on Arbitrum (dstEid 0) or with lzFundsOut to a LayerZero endpoint. Send the record as burnDestination.
See Mint and Burn Integration for a worked example and a test vector.
POST /unlock/verify - Check a Burn Before Unlocking
Takes the same body as POST /unlock and runs the checks POST /unlock makes before it claims the burn: the consignment is a burn, the asset is the bridged RGB asset, the burn reason is the hash of the burnDestination sent for this destination, and the outflow capacity covers the amount. Nothing is claimed, signed or sent, so it can be repeated. It does not check Bitcoin finality, the deposits behind the cited mints, or the reject list. Requires authentication.
Response 200
Errors are as for
POST /unlock: 400 (code 4 for outflow capacity), 401, 404, 409 (already redeemed or being redeemed), 429, 500.
Transfer history
GET /transfers/history/{signature-hex}/{pub-key-hex} — Get Wallet History
Returns a page of the wallet’s mints and burns, newest first. A mint is listed under the wallet that deposited it, a burn under the wallet it paid out to. Requires an API key or session, and the wallet proves ownership with a signature.
Query Parameters
Response
200
Status Values
Error Responses
Poll the history every 5 to 10 seconds. Avoid polling faster: a burn waits for 6 Bitcoin confirmations before its release is signed.
Error Responses
All endpoints return a consistent error envelope on failure.
Codes
6, 7 and 8 come with HTTP 409 from POST /unlock, and a details object with the numbers behind the wait (for example confirmations and requiredConfirmations for code 7). A burn waiting for finality is normally accepted as confirming instead, so these codes are returned only when the bridge could not keep it waiting. Nothing is sent to the EVM network, and the burn stays redeemable. Authentication errors may omit code.