RGB Node API

Overview

The RGB Node API is a self-hosted HTTP service for managing watch-only RGB wallets. It holds no private keys and never signs transactions. Clients identify wallet contexts with xPubs, read wallet state, and sign PSBTs outside the service.

Source repository: UTEXO-Protocol/rgb-node-api. Swagger UI is available at /_swagger when the service is running.

The wallet headers identify a wallet; they are not an authentication mechanism. Place the service behind TLS and an authentication or private-network layer before using it in production.

Base URL

The listen address and port are set in the TOML configuration file passed with -c. If the [api] values are omitted, the service defaults to 127.0.0.1:3000. The repository’s bundled local.uwallet.toml development profile listens on 0.0.0.0:34000, so local requests can use:

http://127.0.0.1:34000

Wallet identification headers

All /wallet/ endpoints require three request headers. The deprecated root-level POST /blindreceive alias requires the same headers.

Header	Description
`xpub-van`	Vanilla xPub for BTC UTXOs
`xpub-col`	Colored xPub for RGB-capable UTXOs
`master-fingerprint`	BIP32 master fingerprint

curl -X POST http://127.0.0.1:34000/wallet/listassets \
  -H "xpub-van: <your-xpub-van>" \
  -H "xpub-col: <your-xpub-col>" \
  -H "master-fingerprint: <your-fingerprint>"

Wallet contexts are registered at runtime through POST /wallet/register; they are not declared in the configuration file.

Configuration

Create a TOML configuration file and pass its path with -c:

[api]
listen_address = "127.0.0.1"
port = 34000

[wallet]
data_dir = "./rgb-data"
network = "regtest"
btc_rpc_address = "127.0.0.1:18443"
btc_rpc_user = "dev"
btc_rpc_password = "dev"
indexer_address = "tcp://127.0.0.1:50001"
proxy_address = ["rpc://127.0.0.1:3000/json-rpc"]

The repository ships local.uwallet.toml for local development. The just run command passes that file to the service automatically.

Running the service

Run the service with your configuration file:

cargo run -- -c config.toml

For local development, start the bundled regtest stack and then the service:

just up
just run

just up starts bitcoind, electrs, and rgb-proxy. just run starts RGB Node with local.uwallet.toml.

Begin/end signing flow

UTXO creation and RGB asset sends use a client-side PSBT flow:

Call the *begin endpoint

Submit the operation parameters. The service returns an unsigned PSBT string.

Sign the PSBT outside RGB Node

Sign with the wallet’s private keys in the client or a dedicated signer. Private keys are never sent to RGB Node.

Call the matching *end endpoint

Submit the signed PSBT. RGB Node finalizes and broadcasts the transaction.

API endpoints

System

These endpoints do not require wallet-identification headers.

Method	Path	Description
`GET`	`/healthcheck`	Check service liveness
`GET`	`/version`	Return application version information
`GET`	`/_swagger`	Open Swagger UI
`GET`	`/_swagger/swagger.yaml`	Retrieve the OpenAPI specification

Wallet management

Method	Path	Description
`POST`	`/wallet/register`	Create or load a watch-only wallet context
`POST`	`/wallet/refresh`	Synchronize wallet state
`POST`	`/wallet/drop`	Remove a wallet context from memory

Balances and state

Method	Path	Description
`POST`	`/wallet/address`	Return a receive address
`POST`	`/wallet/btcbalance`	Return vanilla and colored BTC balances
`POST`	`/wallet/listassets`	List RGB assets held by the wallet
`POST`	`/wallet/assetbalance`	Return the balance for one RGB asset
`POST`	`/wallet/listunspents`	List UTXOs and RGB allocations
`POST`	`/wallet/listtransactions`	List Bitcoin transactions
`POST`	`/wallet/listtransfers`	List transfers for one RGB asset

Asset operations

RGB Node supports NIA issuance only. For CFA or UDA issuance, use the RGB Lightning Node.

Method	Path	Description
`POST`	`/wallet/issueassetnia`	Issue an NIA (Non-Inflatable Asset)
`POST`	`/wallet/blindreceive`	Generate a blinded RGB receive invoice
`POST`	`/wallet/failtransfers`	Mark eligible transfers as failed

The root-level POST /blindreceive route is a deprecated alias for POST /wallet/blindreceive and should not be used in new integrations.

PSBT operations

Method	Path	Description
`POST`	`/wallet/createutxosbegin`	Build an unsigned PSBT for UTXO creation
`POST`	`/wallet/createutxosend`	Finalize UTXO creation with a signed PSBT
`POST`	`/wallet/sendbegin`	Build an unsigned RGB asset-send PSBT
`POST`	`/wallet/sendend`	Finalize an asset send with a signed PSBT

Request and response examples

POST /wallet/register

The request has no JSON body. Supply the three wallet-identification headers. Response 200:

{
  "address": "bcrt1q...",
  "btc_balance": {
    "vanilla": {
      "settled": 0,
      "future": 0,
      "spendable": 0
    },
    "colored": {
      "settled": 0,
      "future": 0,
      "spendable": 0
    }
  }
}

POST /wallet/issueassetnia

Request body:

{
  "ticker": "MYTKN",
  "name": "My Token",
  "amounts": [1000000],
  "precision": 0
}

Response 200:

{
  "asset_id": "rgb1...",
  "ticker": "MYTKN",
  "name": "My Token",
  "details": null,
  "precision": 0,
  "issued_supply": 1000000,
  "timestamp": 1720000000,
  "added_at": 1720000000,
  "balance": {
    "settled": 1000000,
    "future": 1000000,
    "spendable": 1000000
  },
  "media": null
}

POST /wallet/blindreceive

asset_id, amount, and duration_seconds are optional. min_confirmations defaults to 1. Request body:

{
  "asset_id": "rgb1...",
  "amount": 100,
  "duration_seconds": 3600,
  "min_confirmations": 1
}

Response 200:

{
  "invoice": "rgb:...",
  "recipient_id": "...",
  "expiration_timestamp": 1720000000,
  "batch_transfer_idx": 1
}

POST /wallet/sendbegin

Request body:

{
  "recipient_map": {
    "rgb1...": [
      {
        "recipient_id": "...",
        "amount": 100,
        "transport_endpoints": [
          "rpc://127.0.0.1:3000/json-rpc"
        ]
      }
    ]
  },
  "donation": false,
  "fee_rate": 1,
  "min_confirmations": 1
}

Response 200: An unsigned PSBT string.

POST /wallet/sendend

Request body:

{
  "signed_psbt": "cHNidP8B..."
}

Response 200:

{
  "txid": "abc123...",
  "batch_transfer_idx": 2
}

Error handling

The missing-header response is different from the API’s structured error envelope:

Condition	HTTP status	Content type	Response shape
One or more wallet headers are missing	`401 Unauthorized`	Plain text	`Missing xpub-van/xpub-col/master-fingerprint header`
JSON body cannot be deserialized	`422 Unprocessable Entity`	JSON	Structured `error` envelope with code `1001`
RGB, indexer, Bitcoin RPC, storage, or wallet operation fails	`500 Internal Server Error`	JSON	Structured `error` envelope with code `500`

Structured errors use this envelope:

{
  "error": {
    "code": 1001,
    "status": "bad_input",
    "message": "invalid json format",
    "details": {
      "body": "..."
    }
  }
}

Most underlying RGB and dependency errors are currently collapsed to a generic internal error:

{
  "error": {
    "code": 500,
    "status": "internal_error",
    "message": "something went wrong",
    "details": {}
  }
}

The 401 missing-header response bypasses the JSON envelope. Clients should handle it separately.

What Utexo Is

Getting Started

Product Suite

Overview

Base URL

Wallet identification headers

Configuration

Running the service

Begin/end signing flow

API endpoints

System

Wallet management

Balances and state

Asset operations

PSBT operations

Request and response examples

POST /wallet/register

POST /wallet/issueassetnia

POST /wallet/blindreceive

POST /wallet/sendbegin

POST /wallet/sendend

Error handling

​Overview

​Base URL

​Wallet identification headers

​Configuration

​Running the service

​Begin/end signing flow

​API endpoints

​System

​Wallet management

​Balances and state

​Asset operations

​PSBT operations

​Request and response examples

​POST /wallet/register

​POST /wallet/issueassetnia

​POST /wallet/blindreceive

​POST /wallet/sendbegin

​POST /wallet/sendend

​Error handling

Overview

Base URL

Wallet identification headers

Configuration

Running the service

Begin/end signing flow

API endpoints

System

Wallet management

Balances and state

Asset operations

PSBT operations

Request and response examples

POST /wallet/register

POST /wallet/issueassetnia

POST /wallet/blindreceive

POST /wallet/sendbegin

POST /wallet/sendend

Error handling