Skip to main content

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 with GET /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/
The API is stateless and JSON-based. Every endpoint in this reference needs authentication: an API key in the 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-Key header. Send exactly one key; two headers return 400.
  • Session: the customer session cookie set by signing in to the Utexo web app. Browser requests other than GET also need X-Requested-With: XMLHttpRequest and a trusted origin.
A missing or invalid key or session returns 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
All amounts are decimal strings in base units. 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.
Keep the V1 record: a burn cannot be released without it.
Routes used by the Utexo web app (confirm them for your environment): 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.
Error Codes 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.

Data Models

Network

Token


Glossary