> ## Documentation Index
> Fetch the complete documentation index at: https://docs.utexo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mint API Reference

> Network-agnostic REST API for discovering supported networks, estimating fees, initiating transfers, and tracking settlement across EVM, RGB, and RGB Lightning networks.

## 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.

<Info>
  **Base URL (staging):** `https://transfer.gateway.stage.utexo.com/api/v0`

  All paths in this reference are relative to the base URL. Contact the Utexo team for production endpoint access and for an operator API key.

  **Interactive API docs:** [https://transfer.gateway.stage.utexo.com/api/v0/docs/](https://transfer.gateway.stage.utexo.com/api/v0/docs/)
</Info>

The API is stateless and JSON-based. The network, token, estimate and unlock-capacity endpoints are public. The mint and burn endpoints (`/mint/op-id`, `/lock/{opId}/status` and `/unlock`) need an operator API key (see [Authentication](#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).

<Info>
  **RGB network ID:** take the RGB-side network from `GET /networks`. On the current environment it is the `UTEXO` network (ID `96`). The RGB wallet must use an `rgb-lib` version that supports the BFA asset schema, for example [RGB Lightning Node](/rgb-lightning-node/quickstart) `v0.15.0-beta.3` or later.
</Info>

<Warning>
  **RGB Lightning is work in progress.** RGB Lightning network IDs (`94` mainnet, `95` testnet) appear in the API, but Lightning destinations are not available yet. This section will be updated once they go live.
</Warning>

### Lock and mint: EVM → RGB

<Steps>
  <Step title="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.
  </Step>

  <Step title="Estimate the transfer">
    `GET /transfers/estimate/{sender-network}/{recipient-network}/{sender-token-id}/{recipient-token-id}/{amount}` — preview fees and the amount the recipient receives.
  </Step>

  <Step title="Create an RGB invoice">
    The recipient's RGB wallet creates an invoice for the USDT asset.
  </Step>

  <Step title="Prepare the mint">
    `POST /mint/op-id` (operator key) — submit the invoice, the amount and the source network. 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.
  </Step>

  <Step title="Lock USDT0">
    Before `ttlSeconds` runs out, the user calls `fundsIn()` on the Arbitrum bridge contract 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.
  </Step>

  <Step title="Track the mint">
    `GET /lock/{opId}/status` (operator key) — poll until the status is `completed` or `expired`.
  </Step>
</Steps>

### Burn and unlock: RGB → EVM

<Steps>
  <Step title="Check the release capacity">
    `GET /unlock/capacity/{srcNetworkId}/{networkId}/{tokenId}` — read `available`. A burn cannot be undone, so do not burn more than `available`.
  </Step>

  <Step title="Burn USDT on Bitcoin">
    Burn the amount in the RGB wallet and name the EVM recipient. The burn recipient is 32 bytes: 12 zero bytes followed by the 20-byte EVM address. With RGB Lightning Node, call `POST /burn` with `burn_recipient`, then get the burn consignment with `POST /getconsignment` (asset ID and the burn `txid`). It returns the consignment as hex; convert it to base64 for the next step.
  </Step>

  <Step title="Submit the burn consignment">
    `POST /unlock` (operator key) — send the base64-encoded consignment. You can submit it before the burn has its Bitcoin confirmations: until it does, the API returns `409` with code `6`, `7` or `8`, and you retry the same request later.
  </Step>

  <Step title="Confirm the release">
    The response contains the `evmTxHash` of the submitted release and the `recipient` read from the burn. The release confirms on the EVM network asynchronously.
  </Step>
</Steps>

***

## Authentication

### Operator API key

`POST /mint/op-id`, `GET /lock/{opId}/status` and `POST /unlock` need the operator API key in the `X-API-Key` header. A missing or invalid key returns `401`. Keep the key on a trusted backend: do not embed it in a browser app or an untrusted wallet. Contact the Utexo team to get a key.

```bash theme={null}
curl -X POST https://transfer.gateway.stage.utexo.com/api/v0/mint/op-id \
  -H "X-API-Key: <OPERATOR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"networkId": 96, "sourceNetworkId": 42161, "invoice": "rgb:...", "amount": 1000000}'
```

### Signature authentication

The other endpoints need no API key. Three of them authenticate the caller with a signature, differing only in where the signature travels — in the path for `GET /transfers/history/{signature-hex}/{pub-key-hex}`, in the request body for `POST /transfers/verify-bridge-in` and `POST /transfers/submit-transaction`:

| Field | Description |
| - | - |
| `authenticationSignature` | Hex-encoded signature over the fixed message `Bridge Authentication Proof` |
| `publicKey` | Sender address or public key encoded for `networkId` |

**Signing procedure.** The signed message is the constant string `Bridge Authentication Proof`. Verification depends on the network type:

* **EVM and Tron** — the public key is recovered from the signature, converted to an address, and compared against `publicKey`.
* **RGB and RGB Lightning** — authentication is handled inside those networks; no signature check happens at this layer.

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

***

## 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

```json theme={null}
[
  {
    "id": 42161,
    "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`

```json theme={null}
{
  "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"`).

***

### Mint and burn

#### `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 the operator API key.

**Request Body**

```json theme={null}
{
  "networkId": 96,
  "sourceNetworkId": 42161,
  "sourceAddress": "0xYourEvmAddress",
  "invoice": "rgb:...",
  "amount": 1000000
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `networkId` | `integer` | Yes | RGB network ID (not the EVM source chain) |
| `sourceNetworkId` | `integer` | Yes | EVM network the deposit is sent from |
| `sourceAddress` | `string` | No | Address that sends the deposit. Required when the source network uses an entrypoint contract |
| `tokenId` | `integer` | No | Token ID on the source network. Required when the source network uses an entrypoint contract |
| `assetId` | `string` | No | RGB asset ID. Omit to use the standard USDT asset |
| `invoice` | `string` | Yes | Invoice created by the recipient's RGB wallet |
| `amount` | `integer` | Yes | Amount the user deposits, in token base units. For a 6-decimal token, `1000000` is 1 USDT |

**Response `200`**

```json theme={null}
{
  "opId": "9f2c...e41a",
  "ttlSeconds": 1800,
  "settlementData": "0x9f2c...e41a",
  "depositAmount": "1000000",
  "mintAmount": "1000000"
}
```

| Field | Description |
| - | - |
| `opId` | RGB operation ID of the mint. Use it to track the mint |
| `ttlSeconds` | Time available to submit the matching deposit |
| `settlementData` | ABI-encoded `opId`. Pass it verbatim as the `settlementData` argument of `fundsIn()`; do not pass `opId` directly |
| `depositAmount` | Amount to deposit on the source network, in base units |
| `mintAmount` | Amount minted on Bitcoin, in base units. On an entrypoint route it is the amount quoted to arrive on Arbitrum |
| `entrypoint` | Present only when the source network uses an entrypoint contract: `contractAddress`, `depositParams` (`amountLD`, `minAmountLD`, `extraOptions`, `payload`, `refundTo`, `expectedComposeValue`), `networkFee`, `nativeFee` and `totalNativeRequired` |

***

#### `GET /lock/{opId}/status` — Get Mint Status

Returns the state of a prepared mint. Poll it after the deposit is submitted. Requires the operator API key.

**Response `200`**

```json theme={null}
{
  "opId": "9f2c...e41a",
  "status": "broadcast",
  "expiresAt": "2026-10-06T12:30:00Z",
  "evmTxHash": "0xabc..."
}
```

| Status | Description |
| - | - |
| `awaiting_funds_in` | Waiting for the deposit. The mint expires at `expiresAt` if no deposit arrives |
| `funds_in_confirmed` | The deposit was detected and matched to the mint |
| `bridge_signed` | The mint signer signed the mint |
| `broadcast` | The Bitcoin transaction anchoring the mint was broadcast |
| `completed` | The Bitcoin transaction has the required confirmations; the mint is complete |
| `expired` | No matching deposit arrived in time |

`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. No authentication.

**Path Parameters**

| Parameter | Type | Description |
| - | - | - |
| `srcNetworkId` | `integer` | RGB network where the USDT is burned |
| `networkId` | `integer` | EVM network where USDT0 is released |
| `tokenId` | `integer` | Token ID on the EVM network |

**Response `200`**

```json theme={null}
{
  "srcNetworkId": 96,
  "networkId": 42161,
  "tokenId": 2,
  "poolBalance": "1354199",
  "pendingReleases": "0",
  "availableOutflow": "135419",
  "available": "135419"
}
```

| Field | Description |
| - | - |
| `poolBalance` | USDT0 locked in the bridge, in base units |
| `pendingReleases` | Amount reserved by releases still in progress |
| `availableOutflow` | Remaining outflow allowance; omitted when no limit applies |
| `available` | Maximum amount that can be burned and released now |

***

#### `POST /unlock` — Release After a Burn

Validates a burn consignment, gets the release signatures and submits the EVM release. The amount and the recipient are read from the burn itself; the request cannot change them. Requires the operator API key.

**Request Body**

```json theme={null}
{
  "consignment": "<base64-encoded burn consignment>",
  "srcNetworkId": 96,
  "destinationNetworkId": 42161,
  "tokenId": 2
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `consignment` | `string` | Yes | Complete burn consignment, standard base64 |
| `srcNetworkId` | `integer` | No | RGB network of the burn. Optional when the bridge serves one RGB network |
| `destinationNetworkId` | `integer` | No | EVM network of the release. Optional when the bridge serves one EVM network |
| `tokenId` | `integer` | No | Token ID on the EVM network |
| `maxFeeRate` | `string` | No | Cap on the EVM gas price in wei |

**Response `200`**

```json theme={null}
{
  "evmTxHash": "0xabc...",
  "status": "submitted",
  "recipient": "0xYourEvmAddress"
}
```

**Error Responses**

| Status | Meaning |
| - | - |
| `400` | Invalid input, or the release exceeds the current outflow allowance (code `4`). The burn stays redeemable; retry later |
| `401` | `X-API-Key` is missing or invalid |
| `409` | The burn cannot be released yet (codes `6`, `7`, `8`; retry the same request later) or was already released |
| `429` | Rate limit exceeded |
| `500` | Burn validation, signing or EVM submission failed |

***

### Transfers

<Note>
  The pre-registration endpoints in this group (`bridge-in-signature`, `verify-bridge-in`, `submit-transaction` and `invoice`) belong to the earlier transfer flow. Transfers between USDT0 and USDT on Bitcoin use the [mint and burn](#mint-and-burn) endpoints.
</Note>

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

Returns a fee and confirmation time estimate for a proposed transfer. Call it before you prepare the mint to show the user a cost preview.

**Path Parameters**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sender-network` | `string` | Yes | Sender network name (e.g., `ARBITRUM-ONE`, `UTEXO`) |
| `recipient-network` | `string` | Yes | Recipient network name |
| `sender-token-id` | `integer` | Yes | Token ID on the sender network |
| `recipient-token-id` | `integer` | Yes | Token ID on the recipient network |
| `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`

```json theme={null}
{
  "fee": "0.50",
  "feePercentage": "0.5",
  "stableFee": "0.10",
  "estimatedConfirmationTime": "5 minutes",
  "resultAmount": "99.40",
  "nativeFee": "0.0002",
  "networkFee": "0.0001",
  "nativeStableFee": "0.0001",
  "totalNativeCommission": "0.0004",
  "nativeTokenSymbol": "ETH",
  "swapResultAmount": "99.40",
  "effectiveAvailableOutflow": "10000"
}
```

| 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) |
| `networkFee` | Source-network execution fee in the sender's native token |
| `nativeStableFee` | Stable fee in the sender's native token (multi-token transfers) |
| `totalNativeCommission` | Sum of the native fee components |
| `nativeTokenSymbol` | Symbol of the native token used for commissions |
| `swapResultAmount` | Human-readable result amount in recipient token units |
| `effectiveAvailableOutflow` | Remaining destination outflow allowance; omitted when no limit applies |
| `screening` | Present when AML screening is active: `cleared`, or `unavailable` (the transfer must not be started) |
| `clearance` | AML clearance `token` and its `expiresAt`, when screening issued one |

***

#### `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`

```json theme={null}
{
  "sender": {
    "networkId": 42161,
    "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`

```json theme={null}
{
  "token": "0xTokenContractAddress",
  "amount": "100500000",
  "gasCommission": "50000",
  "destination": { ... },
  "deadline": "1719999999",
  "nonce": 7,
  "transferId": 1024,
  "signature": "0x",
  "transferType": "WU",
  "estimation": { ... },
  "totalCommission": "600000"
}
```

| Field | Description |
| - | - |
| `token` | EVM token contract address |
| `amount` | Transfer amount in **smallest token units** (not human-readable) |
| `gasCommission` | Gas commission in smallest token units |
| `destination` | Destination network and address selected for the transfer |
| `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 model. Always `WU` (lock and mint, burn and unlock) — see [Transfer Types](#transfer-types) |
| `estimation` | Fee and result-amount estimation using the same fields as the estimate endpoint |
| `entrypoint` | Ready-to-call entrypoint contract data; present only when the selected route uses the entrypoint contract |
| `totalCommission` | Total commission in smallest token units |

***

#### `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`

```json theme={null}
{
  "transferId": 1024,
  "networkId": 42161,
  "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**

| 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. Populate this field only when required for the selected network. |
| `publicKey` | `string` | Yes | Sender address or public key encoded for `networkId` |
| `authenticationSignature` | `string` | Yes | Hex-encoded signature proving sender ownership |

**Response `200`**

```json theme={null}
{
  "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/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`

```json theme={null}
{
  "transfers": [...],
  "offset": 0,
  "limit": 20,
  "totalCount": 142
}
```

**Transfer Status Values**

| Status | Description |
| - | - |
| `WAITING` | Transfer registered, awaiting on-chain confirmation |
| `CONFIRMING` | On-chain transaction detected, awaiting sufficient confirmations |
| `FINISHED` | Transfer completed successfully |
| `FAILED` | Transfer failed — check `outboundTx` for details |

<Info>
  Poll history 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.
</Info>

***

#### `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`

```json theme={null}
{
  "invoice": "rgb:..."
}
```

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

***

## Transfer Types

The `transferType` field in `BridgeInSignatureData` names the transfer model the bridge uses. The Mint uses a single model, returned as `WU`:

| Value | Description |
| - | - |
| `WU` | Lock and mint: USDT0 is locked on Arbitrum and USDT is minted on Bitcoin. Burn and unlock: USDT on Bitcoin is burned and USDT0 is unlocked on Arbitrum. |

Clients can treat this field as informational.

***

## Error Responses

All endpoints return a consistent error envelope on failure.

```json theme={null}
{
  "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 (the bridge cannot cover the transfer) |
| `4` | Destination outflow limit exceeded. Retry after capacity recovers |
| `5` | AML policy or clearance failure |
| `6` | Release wait: the Bitcoin relay has not reached the burn block yet |
| `7` | Release wait: the burn does not have enough Bitcoin confirmations yet |
| `8` | Release wait: the on-chain verifier refused the relay depth or freshness |
| `65535` | Other / unclassified error |

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`). Nothing is sent to the EVM network, and the burn stays redeemable.

***

## Data Models

### `Address`

```json theme={null}
{
  "networkId": 42161,
  "networkName": "ARBITRUM-ONE",
  "address": "0x..."
}
```

### `Network`

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

### `Token`

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

***

## 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. |
| **OpId** | The RGB operation ID of a prepared mint, returned by `POST /mint/op-id`. |
| **settlementData** | The ABI-encoded OpId the deposit carries to bind it to the prepared mint. |
| **Burn consignment** | The RGB data that proves a burn. `POST /unlock` reads the release amount and recipient from it. |
| **transferId** | The internal identifier of a transfer pre-registered with `bridge-in-signature` (earlier flow). |
| **Triggering Tx** | The EVM deposit transaction that starts a lock-and-mint transfer. |
| **Entrypoint contract** | A per-network contract that forwards a deposit to the Arbitrum hub through LayerZero. When a route uses it, `POST /mint/op-id` returns an `entrypoint` object and the user calls that contract instead of `fundsIn()`. |
| **UTXO** | Unspent Transaction Output — the fundamental unit of Bitcoin accounting. RGB asset state is anchored to UTXOs. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.