Mint API Reference

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, Tron, and Solana reach that hub through LayerZero. Arbitrum is currently the only live network in this environment. For now, the only tested and available route is Arbitrum (mainnet) to Bitcoin (Utexo signet). Bitcoin mainnet is not available yet.

Base URL (testnet / dev): https://transfer.dev.utexo.com/api/v0All paths in this reference are relative to the base URL. A mainnet base URL will be provided separately. Contact the Utexo team for production endpoint access.

The API is stateless and JSON-based. GET requests need no authentication. The POST /transfers/verify-bridge-in and POST /transfers/submit-transaction endpoints need a signature in the request body (see Authentication).

Transfer Flows

Understanding the transfer direction is essential before making any API calls. The API supports two directions:

RGB and Lightning destinations: The RGB-side destination is selected by networkId. Use 36 (mainnet) or 91 (testnet) for plain RGB, and 94 (mainnet) or 95 (testnet) for RGB Lightning. The destination accepts an RGB invoice (rgb:…) for plain RGB or a Lightning invoice string for RGB Lightning. Network ID 96 identifies Utexo and is not a Lightning network ID.

EVM → RGB or RGB Lightning

Move assets from an EVM network to a plain RGB or RGB Lightning destination.

Discover networks and tokens

GET /networks — list all connected networks.GET /networks/{network-id}/supported-tokens — list tokens supported on a given network.

Estimate fees

GET /transfers/estimate/{sender-network}/{recipient-network}/{token-id}/{amount} — get fee and confirmation time estimate before committing.

Pre-register the transfer

POST /transfers/bridge-in-signature — pre-register the transfer. Returns a transferId, fee estimation, and an empty signature (0x).

Call fundsIn() on the EVM contract

The user calls fundsIn() directly on the EVM bridge contract using the data returned in Step 3. This step happens client-side — the API does not broadcast this transaction.

Confirm the transaction

POST /transfers/verify-bridge-in — notify the mint with the on-chain tx hash to confirm the transfer.

Poll transfer status

GET /transfers/{tx} — poll using the triggering tx hash until the transfer reaches a terminal status (FINISHED, CANCELLED, or FAILED).

Retrieve destination invoice (optional)

GET /transfers/invoice/{tx-id}/{network-id} — fetch the RGB or Lightning invoice selected by network-id.

RGB or RGB Lightning → EVM

Move assets from a plain RGB or RGB Lightning wallet to an EVM network.

Discover networks and tokens

Same as EVM → RGB Step 1.

Estimate fees

Same as EVM → RGB Step 2.

Pre-register the transfer

POST /transfers/bridge-in-signature — returns the invoice for the selected RGB-side network in the signature field: an RGB invoice for plain RGB or a Lightning invoice for RGB Lightning.

Send RGB assets

The user pays the invoice string returned in Step 3 with the wallet appropriate for the selected RGB or RGB Lightning network.

Confirm the transfer

POST /transfers/verify-bridge-in — notify the mint that the RGB or Lightning invoice payment has been completed.

Poll transfer status

GET /transfers/{tx} — poll for status as in the EVM → RGB flow.

Authentication

Read-only endpoints (all GET requests) and POST /transfers/bridge-in-signature require no authentication header. The POST /transfers/verify-bridge-in and POST /transfers/submit-transaction endpoints validate the caller’s identity using a cryptographic signature embedded in the request body:

Field	Description
`authenticationSignature`	Hex-encoded signature proving ownership of the sender address
`publicKey`	Sender address or public key encoded for `networkId`

A 401 response indicates an invalid authentication signature. A 403 response indicates the derived sender address does not match the pre-registered transfer.

The authentication scheme (signing algorithm, message format) is not formally specified in the current API spec. Validation required — contact the Utexo team for the canonical signing procedure before implementing.

Endpoints

Networks

`GET /networks` — List Connected Networks

Returns all connected networks. Optionally filter by token, source network, or name. Query Parameters

Parameter	Type	Required	Description
`token-id`	`integer`	No	Filter results to networks that support this token ID. Cannot be combined with `source-network-id`.
`source-network-id`	`integer`	No	Return networks supported by the specified source network. Cannot be combined with `token-id`.
`search`	`string`	No	Filter results by network name (partial match)

Response 200 — Array of Network objects

[
  {
    "id": 84,
    "name": "ARBITRUM-ONE",
    "displayName": "Arbitrum One",
    "type": "NT_EVM",
    "bridgeContract": "0x...",
    "gasLimit": 200000,
    "iconLink": "https://...",
    "active": true,
    "explorerBaseUrl": "https://arbiscan.io"
  }
]

`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

Parameter	Type	Required	Description
`network-id`	`integer`	Yes	The network ID

Query Parameters

Parameter	Type	Required	Description
`token-id`	`integer`	No	If set, returns a single `Token` object instead of a paginated list
`search`	`string`	No	Filter tokens by name or symbol
`limit`	`integer`	No	Number of results per page
`page`	`integer`	No	Page number (1-indexed)

Response 200 — SupportedTokensResponse

The SupportedTokensResponse fields are PascalCase in the JSON response (e.g., Tokens, Limit, PageCount). This is a Go struct serialization artifact with no json tags. Deserialize accordingly.

{
  "Tokens": [...],
  "Limit": 20,
  "Offset": 0,
  "PageCount": 3,
  "CurrentPage": 1,
  "TotalCount": 45
}

`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

Parameter	Type	Required	Description
`network-id`	`integer`	Yes	The network ID
`token-id`	`integer`	Yes	The token ID
`user-address`	`string`	Yes	User address. For EVM networks, provide a hex-encoded address (with or without `0x` prefix).

Response 200 — string Balance as a human-readable decimal string in token units (e.g., "100.50").

`GET /networks/{network-id}/fetch-user-tokens/{user-address}` — Fetch User Multitokens

Requests the gateway to fetch the user’s multitoken holdings for the specified network and address. Path Parameters

Parameter	Type	Required	Description
`network-id`	`integer`	Yes	Network ID. The handler validates that the ID is registered.
`user-address`	`string`	Yes	User address encoded for the selected network.

Response 200 — Empty body. The current handler writes no JSON response on success. Error Responses

Status	Meaning
`400`	Invalid network ID or user address
`500`	The gateway could not fetch the user’s multitokens

Transfers

`GET /transfers/estimate/{sender-network}/{recipient-network}/{token-id}/{amount}` — Estimate Transfer Fees

Returns a fee and confirmation time estimate for a proposed transfer. Call this before pre-registering to give users a cost preview. Path Parameters

Parameter	Type	Required	Description
`sender-network`	`string`	Yes	Sender network name (e.g., `ARBITRUM-ONE`, `RGB`)
`recipient-network`	`string`	Yes	Recipient network name
`token-id`	`integer`	Yes	Token ID — the same token is bridged on both sides
`amount`	`string`	Yes	Human-readable amount (e.g., `100.5`)

Query Parameters

Parameter	Type	Required	Description
`sender-address`	`string`	Yes	Sender’s address on the sender network
`recipient-address`	`string`	Yes	Recipient’s address on the recipient network

Response 200 — Estimation

{
  "fee": "0.50",
  "feePercentage": "0.5",
  "stableFee": "0.10",
  "estimatedConfirmationTime": "5 minutes",
  "resultAmount": "99.40",
  "nativeFee": "0.0002",
  "nativeStableFee": "0.0001",
  "totalNativeCommission": "0.0003",
  "nativeTokenSymbol": "ETH",
  "swapResultAmount": "99400000"
}

Field	Description
`fee`	Gas fee denominated in the transfer token
`stableFee`	Fixed protocol fee in transfer token units
`feePercentage`	Protocol fee as a percentage string
`resultAmount`	Amount the recipient will receive after fees
`nativeFee`	Gas fee in the sender’s native token (multi-token transfers)
`nativeStableFee`	Stable fee in the sender’s native token (multi-token transfers)
`totalNativeCommission`	Sum of `nativeFee` + `nativeStableFee`
`nativeTokenSymbol`	Symbol of the native token used for commissions
`swapResultAmount`	Result amount in the recipient token’s smallest units

`POST /transfers/bridge-in-signature` — Pre-Register Transfer

Pre-registers a transfer and returns the data needed for the user to initiate the on-chain action.

EVM → RGB or RGB Lightning: Returns transferId, fee estimation, and an empty signature field (0x). The user then calls fundsIn() on the EVM bridge contract.
RGB or RGB Lightning → EVM: Returns the invoice string for the selected RGB-side network in the signature field. The user pays that RGB or Lightning invoice.

Request Body — BridgeInSignatureRequest

{
  "sender": {
    "networkId": 84,
    "networkName": "ARBITRUM-ONE",
    "address": "0xYourEvmAddress"
  },
  "tokenId": 42,
  "amount": "100.5",
  "destination": {
    "networkId": 36,
    "networkName": "RGB",
    "address": "rgb:..."
  },
  "additionalAddresses": []
}

Field	Type	Required	Description
`sender`	`Address`	Yes	Sender network, ID, and address
`tokenId`	`integer`	Yes	Token ID (same token on both chains)
`amount`	`string`	Yes	Human-readable amount (e.g., `"100.5"`)
`destination`	`Address`	Yes	Recipient network, ID, and address
`additionalAddresses`	`string[]`	No	Additional addresses (use case: TBD — validation required)

Response 200 — BridgeInSignatureData

{
  "token": "0xTokenContractAddress",
  "amount": "100500000",
  "gasCommission": "50000",
  "destination": { ... },
  "deadline": "1719999999",
  "nonce": 7,
  "transferId": 1024,
  "signature": "0x",
  "transferType": "LP",
  "estimation": { ... },
  "totalCommission": "600000"
}

Field	Description
`token`	EVM token contract address
`amount`	Transfer amount in smallest token units (not human-readable)
`deadline`	EVM: UNIX timestamp expiry. RGB: always `"0"`
`nonce`	Nonce for the EVM bridge contract call
`transferId`	Internal transfer ID — store this for use in `verify-bridge-in`
`signature`	EVM → RGB/RGB Lightning: `"0x"` (empty). RGB/RGB Lightning → EVM: RGB or Lightning invoice string selected by destination network ID
`transferType`	Transfer routing type — see Transfer Types
`totalCommission`	Total commission in smallest token units

`GET /transfers/cancel-signature/{transfer-id}/{network-id}/{signature}/{public-key}` — Request Cancellation Signature

The route is registered, but cancellation is currently unavailable. The handler returns 501 Not Implemented before parsing any path parameters or producing a cancellation signature. Path Parameters

Parameter	Type	Required	Description
`transfer-id`	`integer`	Yes	Reserved transfer ID segment; not currently parsed
`network-id`	`integer`	Yes	Reserved network ID segment; not currently parsed
`signature`	`string`	Yes	Reserved signature segment; not currently parsed
`public-key`	`string`	Yes	Reserved public key segment; not currently parsed

Response 501 — Standard error envelope with the message cancelling is unavailable.

Do not build a cancellation flow against this endpoint until the handler is enabled.

`POST /transfers/verify-bridge-in` — Confirm Bridge-In Transaction

Notifies the bridge that the user has completed the on-chain or off-chain send action. Must be called after:

The EVM fundsIn() transaction is broadcast (EVM → RGB/RGB Lightning), or
The RGB or Lightning invoice payment is complete (RGB/RGB Lightning → EVM)

Request Body — VerifyBridgeInRequest

{
  "transferId": 1024,
  "networkId": 84,
  "txHash": "abcdef1234...",
  "publicKey": "0xYourPublicKeyOrAddress",
  "authenticationSignature": "hex-encoded-signature"
}

Field	Type	Required	Description
`transferId`	`integer`	Yes	Transfer ID from `bridge-in-signature` response
`networkId`	`integer`	Yes	Sender’s network ID
`txHash`	`string`	Conditional	Network-encoded transaction hash. May be empty when the RGB-side confirmation has no transaction hash to submit.
`publicKey`	`string`	Yes	Sender public key or address
`authenticationSignature`	`string`	Yes	Hex-encoded signature proving address ownership

Response 200 — Empty body (null). Accepted. Error Responses

Status	Meaning
`401`	Authentication signature is invalid
`403`	Sender address derived from the signature does not match the pre-registered transfer
`500`	Internal server error

`POST /transfers/submit-transaction` — Submit Signed Transaction

Submits signed transaction data for a pre-registered transfer and returns the resulting transaction hash. Request Body

{
  "transferId": 1024,
  "networkId": 26,
  "txData": "base64-encoded-transaction",
  "publicKey": "sender-address-or-public-key",
  "authenticationSignature": "hex-encoded-signature"
}

Field	Type	Required	Description
`transferId`	`integer`	Yes	Transfer ID from `POST /transfers/bridge-in-signature`
`networkId`	`integer`	Yes	Network on which the transaction is submitted
`txData`	`string`	Conditional	Base64-encoded signed transaction data. Non-empty data is currently accepted only for Bitcoin and Concordium network types.
`publicKey`	`string`	Yes	Sender address or public key encoded for `networkId`
`authenticationSignature`	`string`	Yes	Hex-encoded signature proving sender ownership

Response 200

{
  "txHash": "network-encoded-transaction-hash"
}

Error Responses

Status	Meaning
`400`	Invalid network, sender address, signature encoding, transaction encoding, or unsupported non-empty `txData` network type
`401`	Authentication signature is invalid
`403`	Sender address does not match the pre-registered transfer
`500`	Transaction submission failed

`GET /transfers/{tx}` — Get Transfer Status

Returns the current state of a transfer identified by its triggering transaction hash. Poll this endpoint after calling verify-bridge-in until the transfer reaches a terminal status. Path Parameters

Parameter	Type	Required	Description
`tx`	`string`	Yes	Triggering tx hash, hex-encoded without `0x` prefix

Response 200 — Array of Transfer objects

[
  {
    "id": 1024,
    "senderAmount": "100.5",
    "recipientAmount": "99.9",
    "commission": "0.6",
    "status": "FINISHED",
    "createdAt": "2026-06-18T09:00:00Z",
    "sender": { "networkId": 84, "networkName": "ARBITRUM-ONE", "address": "0x..." },
    "recipient": { "networkId": 36, "networkName": "RGB", "address": "rgb:..." },
    "senderToken": { "id": 42, "shortName": "USDT", "longName": "Tether USD", "iconLink": "..." },
    "recipientToken": { ... },
    "triggeringTx": { "networkName": "ARBITRUM-ONE", "hash": "abc123..." },
    "outboundTx": { "networkName": "RGB", "hash": "def456..." }
  }
]

Transfer Status Values

Status	Description
`WAITING`	Transfer registered, awaiting on-chain confirmation
`CONFIRMING`	On-chain transaction detected, awaiting sufficient confirmations
`ETCHING`	RGB asset inscription in progress
`FINISHED`	Transfer completed successfully
`CANCELING`	Cancellation in progress
`CANCELLED`	Transfer was cancelled
`FAILED`	Transfer failed — check `outboundTx` for details

Poll GET /transfers/{tx} at a reasonable interval (e.g., every 5–10 seconds). Avoid aggressive polling — the bridge requires Bitcoin confirmations for RGB-leg completions, which may take several minutes.

`GET /transfers/history/{signature-hex}/{pub-key-hex}` — Get Transfer History

Returns a paginated list of transfers associated with a user’s address. Identity is proven by providing a signature. Path Parameters

Parameter	Type	Required	Description
`signature-hex`	`string`	Yes	Hex-encoded signature proving address ownership
`pub-key-hex`	`string`	Yes	Public key or address encoded for the selected network

Query Parameters

Parameter	Type	Required	Description
`offset`	`integer`	Yes	Pagination offset (number of records to skip)
`limit`	`integer`	Yes	Number of records to return (must be > 0)
`network-id`	`integer`	Yes	Network ID to filter history by
`address`	`string`	No	User address — required for Bitcoin native addresses

Response 200 — Page

{
  "transfers": [...],
  "offset": 0,
  "limit": 20,
  "totalCount": 142
}

`GET /transfers/invoice/{tx-id}/{network-id}` — Get RGB or Lightning Invoice

Returns the invoice associated with a completed or pending transfer. The network-id selects plain RGB (36 mainnet, 91 testnet) or RGB Lightning (94 mainnet, 95 testnet). Path Parameters

Parameter	Type	Required	Description
`tx-id`	`integer`	Yes	Internal transfer ID (from `bridge-in-signature` response)
`network-id`	`integer`	Yes	RGB or RGB Lightning network ID

Response 200 — InvoiceResponse

{
  "invoice": "rgb:..."
}

For an RGB Lightning network ID, invoice contains the Lightning invoice string instead.

Transfer Types

The transferType field in BridgeInSignatureData indicates the internal routing mechanism selected for the transfer. Known values:

Value	Description
`LP`	Liquidity pool route
`WU`	Wire-up route
`CCTP`	Circle Cross-Chain Transfer Protocol
`NTV`	Native token transfer
`MLT`	Multi-leg transfer
`BDXS`	Bridge-DEX swap
`LPN`	Lightning-pegged native

The semantic definitions of transferType values are not formally documented in the API spec. The descriptions above are inferred from naming conventions. Validation required — consult the Utexo engineering team before building routing-dependent logic on this field.

Error Responses

All endpoints return a consistent error envelope on failure.

{
  "error": "human-readable error message",
  "code": 1
}

Error Codes

Code	Meaning
`1`	RGB protocol error
`2`	User balance error (insufficient funds)
`3`	System balance error (bridge liquidity issue)
`65535`	Other / unclassified error

Data Models

`Address`

{
  "networkId": 84,
  "networkName": "ARBITRUM-ONE",
  "address": "0x..."
}

`Network`

{
  "id": 84,
  "name": "ARBITRUM-ONE",
  "displayName": "Arbitrum One",
  "type": "NT_EVM",
  "bridgeContract": "0x...",
  "gasLimit": 200000,
  "iconLink": "https://...",
  "active": true,
  "explorerBaseUrl": "https://arbiscan.io"
}

`Token`

{
  "id": 42,
  "shortName": "USDT",
  "longName": "Tether USD",
  "smartContractAddress": "0x...",
  "decimals": 6,
  "iconLink": "https://...",
  "active": true,
  "native": false
}

Open Questions & Unresolved Issues

The following items require validation from the Utexo engineering or product team before this reference is considered complete:

Authentication signing procedure — The message format and signing algorithm for authenticationSignature are not defined in the Swagger spec. Developers cannot implement verify-bridge-in or history without this information.
transferType enum semantics — The values LP, WU, CCTP, NTV, MLT, BDXS, LPN appear in the spec enum but are not described. If transfer type affects the caller’s required behavior (e.g., approvals, contract calls), this must be documented.
additionalAddresses field — Present in BridgeInSignatureRequest but its purpose and expected values are undocumented. Needs clarification.
Mainnet base URL — The current spec host is empty; transfer.dev.utexo.com is the dev/testnet environment. The production base URL must be published before this reference goes external.
SupportedTokensResponse PascalCase fields — Confirmed from the spec (NOTE: fields are PascalCase). This is an unusual JSON convention and should be explicitly called out in SDK wrappers or normalized in a future API version.

Glossary

Term	Definition
RGB	A client-side validated smart contract protocol built on Bitcoin. Assets are issued and transferred using Bitcoin UTXOs as state anchors.
RGB Invoice	A blinded payment request string used to receive RGB assets. Contains blinded UTXO data to preserve receiver privacy.
EVM	Ethereum Virtual Machine — the execution environment used by Arbitrum and other compatible chains.
Bridge Contract	The EVM smart contract that locks or releases assets on the EVM side of a cross-chain transfer.
`fundsIn()`	The method on the EVM bridge contract the sender calls to deposit assets for minting.
transferId	The mint’s internal identifier for a pre-registered transfer. Used in `verify-bridge-in` and invoice retrieval.
Triggering Tx	The transaction or payment event that initiates the mint: the EVM deposit transaction for EVM → RGB/RGB Lightning, the RGB send for RGB → EVM, or the Lightning invoice payment for RGB Lightning → EVM.
UTXO	Unspent Transaction Output — the fundamental unit of Bitcoin accounting. RGB asset state is anchored to UTXOs.

What Utexo Is

Getting Started

Product Suite

API Reference

Overview

Transfer Flows

EVM → RGB or RGB Lightning

RGB or RGB Lightning → EVM

Authentication

Endpoints

Networks

`GET /networks` — List Connected Networks

`GET /networks/{network-id}/supported-tokens` — List Supported Tokens

`GET /networks/{network-id}/balance/{token-id}/{user-address}` — Get User Token Balance

`GET /networks/{network-id}/fetch-user-tokens/{user-address}` — Fetch User Multitokens

Transfers

`GET /transfers/estimate/{sender-network}/{recipient-network}/{token-id}/{amount}` — Estimate Transfer Fees

`POST /transfers/bridge-in-signature` — Pre-Register Transfer

`GET /transfers/cancel-signature/{transfer-id}/{network-id}/{signature}/{public-key}` — Request Cancellation Signature

`POST /transfers/verify-bridge-in` — Confirm Bridge-In Transaction

`POST /transfers/submit-transaction` — Submit Signed Transaction

`GET /transfers/{tx}` — Get Transfer Status

`GET /transfers/history/{signature-hex}/{pub-key-hex}` — Get Transfer History

`GET /transfers/invoice/{tx-id}/{network-id}` — Get RGB or Lightning Invoice

Transfer Types

Error Responses

Data Models

`Address`

`Network`

`Token`

Open Questions & Unresolved Issues

Glossary

​Overview

​Transfer Flows

​EVM → RGB or RGB Lightning

​RGB or RGB Lightning → EVM

​Authentication

​Endpoints

​Networks

​GET /networks — List Connected Networks

​GET /networks/{network-id}/supported-tokens — List Supported Tokens

​GET /networks/{network-id}/balance/{token-id}/{user-address} — Get User Token Balance

​GET /networks/{network-id}/fetch-user-tokens/{user-address} — Fetch User Multitokens

​Transfers

​GET /transfers/estimate/{sender-network}/{recipient-network}/{token-id}/{amount} — Estimate Transfer Fees

​POST /transfers/bridge-in-signature — Pre-Register Transfer

​GET /transfers/cancel-signature/{transfer-id}/{network-id}/{signature}/{public-key} — Request Cancellation Signature

​POST /transfers/verify-bridge-in — Confirm Bridge-In Transaction

​POST /transfers/submit-transaction — Submit Signed Transaction

​GET /transfers/{tx} — Get Transfer Status

​GET /transfers/history/{signature-hex}/{pub-key-hex} — Get Transfer History

​GET /transfers/invoice/{tx-id}/{network-id} — Get RGB or Lightning Invoice

​Transfer Types

​Error Responses

​Data Models

​Address

​Network

​Token

​Open Questions & Unresolved Issues

​Glossary

Overview

Transfer Flows

EVM → RGB or RGB Lightning

RGB or RGB Lightning → EVM

Authentication

Endpoints

Networks

`GET /networks` — List Connected Networks

`GET /networks/{network-id}/supported-tokens` — List Supported Tokens

`GET /networks/{network-id}/balance/{token-id}/{user-address}` — Get User Token Balance

`GET /networks/{network-id}/fetch-user-tokens/{user-address}` — Fetch User Multitokens

Transfers

`GET /transfers/estimate/{sender-network}/{recipient-network}/{token-id}/{amount}` — Estimate Transfer Fees

`POST /transfers/bridge-in-signature` — Pre-Register Transfer

`GET /transfers/cancel-signature/{transfer-id}/{network-id}/{signature}/{public-key}` — Request Cancellation Signature

`POST /transfers/verify-bridge-in` — Confirm Bridge-In Transaction

`POST /transfers/submit-transaction` — Submit Signed Transaction

`GET /transfers/{tx}` — Get Transfer Status

`GET /transfers/history/{signature-hex}/{pub-key-hex}` — Get Transfer History

`GET /transfers/invoice/{tx-id}/{network-id}` — Get RGB or Lightning Invoice

Transfer Types

Error Responses

Data Models

`Address`

`Network`

`Token`

Open Questions & Unresolved Issues

Glossary