# Rarebl API Documentation

> The Rarebl Open API (v1 and v2) gives blockchain data and tools for Bitcoin, Litecoin, Bitcoin Cash, Dash, Ethereum and TRON from Rarebl's own nodes: 42 HTTP endpoints at https://api.rarebl.com/open/<module>/<action> (reads are GET, v2 writes are POST with a JSON body), a WebSocket stream, webhooks, market prices and signing SDKs. No API keys.

## Basics
- **Base URL:** `https://api.rarebl.com/open`
- **Chains (`chain` parameter):** btc, ltc, bch, dash, eth, tron
- **Authentication:** none; `X-API-KEY` is reserved and ignored
- **Rate limits (per IP, by class):** read 5/s burst 20; compute 2/s burst 10; write 6/min burst 3 and 300/day; watch 30/min; hooks 10/min; stream 3 connections; HTTP 429 with Retry-After
- **Sending:** sign locally with an SDK (recommended), sign the digests yourself, or hosted signing (sends a key to Rarebl; needs the header X-Rarebl-Accept-Risk: hosted-signing)
- **Envelope:** `{status, code, message, data, go, meta:{requestid, notices}}` (quote `meta.requestid`, or the `X-Request-Id` header, to support); codes API200, API400, API403, API404, API405, API409, API422, API429, API502, API500
- **Postman:** https://docs.rarebl.com/collections/rarebl-api.postman_collection.json

This file combines the Rarebl guides and the full API reference for LLM ingestion.

# Human documentation

# Documentation

The Rarebl Open API gives you blockchain data and tools for Bitcoin, Litecoin, Bitcoin Cash, Dash, Ethereum and TRON, served from Rarebl's own nodes: read data, build and broadcast transactions, webhooks, a live stream and market prices. Use the guides when you need context, then switch to API Reference for exact request and response details.

The API is available at `https://api.rarebl.com`, with endpoints under `/open/<module>/<action>`. See [Coverage and limits](https://docs.rarebl.com/limits-today) for what is available on each chain.

## Jump right in

- [Quickstart](https://docs.rarebl.com/quickstart): Make your first call with curl and read the response envelope.
- [Look up a transaction](https://docs.rarebl.com/api/tx/get): Fetch any transaction by hash on Bitcoin, Litecoin, Bitcoin Cash, Dash, Ethereum or TRON.
- [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction): Build, verify, sign on your machine and broadcast, step by step.
- [Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally): JavaScript, Python, PHP and shell SDKs: your keys never leave your machine.
- [Track a deposit](https://docs.rarebl.com/guides/track-a-deposit): Poll tx/status until a payment reaches your confirmation threshold.
- [Webhooks](https://docs.rarebl.com/guides/webhooks): Signed deliveries for blocks, confirmations, addresses and token transfers. No account.
- [Market prices and fees](https://docs.rarebl.com/guides/market-data): Reference prices, FX rates and live network fees for every chain.
- [Chains & units](https://docs.rarebl.com/chains-and-units): The six chains, decimals, address formats and amount conventions.
- [Postman collection](https://docs.rarebl.com/collections/rarebl-api.postman_collection.json): Download the generated collection and environment and call all 42 endpoints.

## Postman collection

Download [the collection](https://docs.rarebl.com/collections/rarebl-api.postman_collection.json) and [the environment](https://docs.rarebl.com/collections/rarebl-live.postman_environment.json), then import both into Postman. Both are generated from these docs.

## Support

Email [hello@rarebl.com](mailto:hello@rarebl.com) or message [WhatsApp](https://wa.me/233551648687). Include the request (chain and hash or address) and the full reply.

## Requests and responses

Reads take `GET` with query parameters (v1 reads also accept a JSON `POST`); v2 writes take `POST` with a JSON body. Every reply is `{status, code, message, data, go}` with a code from API200 to API500. See [Responses & codes](https://docs.rarebl.com/responses-and-codes).

## Authentication

None: no keys and no accounts. Clients are limited per IP, by rate class. `X-API-KEY` is reserved and ignored. See [Authentication](https://docs.rarebl.com/authentication) and [Rate limits](https://docs.rarebl.com/rate-limits).

## Next steps

- [Quickstart](https://docs.rarebl.com/quickstart)
- [API reference](https://docs.rarebl.com/api)
- [Track a deposit until it confirms](https://docs.rarebl.com/guides/track-a-deposit)
- [Coverage and limits](https://docs.rarebl.com/limits-today)

Docs: https://docs.rarebl.com

---

# Quickstart

Make your first Rarebl Open API calls in about two minutes: list the chains, check a transaction and read a price. The API serves **Bitcoin, Litecoin, Bitcoin Cash, Dash, Ethereum and TRON** from Rarebl's own nodes. There is no account and no API key.

## Before you start

- `curl`, or any HTTP client. Every example below also has JavaScript, Python, PHP or shell tabs.
- Nothing else: no sign-up and no key. Clients are limited per IP address ([Rate limits](https://docs.rarebl.com/rate-limits)).

The base URL is `https://api.rarebl.com/open/<module>/<action>`. Reads are `GET` with query parameters (or `POST` with a JSON body); most take a `chain`: `btc`, `ltc`, `bch`, `dash`, `eth` or `tron`.

## Step 1 — List the chains

Ask which chains exist and whether they are healthy.

```bash cURL
curl "https://api.rarebl.com/open/stats/chains"
```

```js JavaScript
const res = await fetch('https://api.rarebl.com/open/stats/chains');
const body = await res.json();
console.log(body.data.chains.map((c) => `${c.id} ${c.status} ${c.tip?.height}`));
```

```python Python
import json, urllib.request

with urllib.request.urlopen("https://api.rarebl.com/open/stats/chains") as r:
    body = json.load(r)
print([(c["id"], c["status"], c["tip"] and c["tip"]["height"]) for c in body["data"]["chains"]])
```

```php PHP
<?php
$body = json_decode(file_get_contents('https://api.rarebl.com/open/stats/chains'), true);
foreach ($body['data']['chains'] as $c) { echo "{$c['id']} {$c['status']}\n"; }
```

**You should see** the envelope below, with one entry per chain (shortened to Bitcoin here).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "chains": [
      { "id": "btc", "name": "Bitcoin", "symbol": "BTC", "decimals": 8, "kind": "utxo", "status": "ok",
        "tip": { "height": 975869, "hash": "000000000000000000018a26062659ab25520a26b803d3e4ec9568a85c3f4235", "time": "2026-11-15T01:00:09Z" },
        "historyFrom": null,
        "features": { "addressHistory": false, "addressBalance": false, "tokens": false, "mempool": true, "internalTxs": false } }
    ]
  },
  "go": null,
  "meta": { "requestid": "0123456789abcdef", "notices": [] }
}
```

## Step 2 — Read the envelope

Every reply, success or error, has the same five fields, followed by a `meta` object. Branch on `code`, never on `message`.

| Field | Meaning |
| --- | --- |
| `status` | `1` for success, `0` for an error. |
| `code` | `API200` on success; otherwise an error code such as `API400` or `API429` ([Responses & codes](https://docs.rarebl.com/responses-and-codes)). |
| `message` | Human-readable text. It can change, so do not parse it. |
| `data` | The payload. On an error it can carry `param`, `reason` or `detail`. |
| `go` | Reserved, always `null`. |
| `meta` | `meta.requestid` is the id of this request (also sent as the `X-Request-Id` header); `meta.notices` is an array of advisory notices, empty when there are none. |

Every reply also has the headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-Request-Id`. Quote `meta.requestid` (or `X-Request-Id`) when you ask for support.

## Step 3 — Check a transaction

Use [Transaction status](https://docs.rarebl.com/api/tx/status) for a small, fast reply. Pass the `chain` and the transaction hash as `id`.

```bash cURL
curl "https://api.rarebl.com/open/tx/status?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db"
```

```js JavaScript
const url = 'https://api.rarebl.com/open/tx/status?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db';
const { data } = await (await fetch(url)).json();
console.log(data.status, data.confirmations);
```

```python Python
import json, urllib.request

url = "https://api.rarebl.com/open/tx/status?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db"
data = json.load(urllib.request.urlopen(url))["data"]
print(data["status"], data["confirmations"])
```

```php PHP
<?php
$url = 'https://api.rarebl.com/open/tx/status?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db';
$data = json_decode(file_get_contents($url), true)['data'];
echo $data['status'], ' ', $data['confirmations'], "\n";
```

```bash Shell
rarebl status --chain btc 9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db
```

**You should see** `status: "success"` and a confirmation count that grows with every block.

```json
{
  "status": 1, "code": "API200", "message": "success",
  "data": { "hash": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db", "status": "success", "block": 975851, "confirmations": 20, "time": "2026-11-14T22:18:52Z" },
  "go": null,
  "meta": { "requestid": "0123456789abcdef", "notices": [] }
}
```

For the full transaction (inputs, outputs, fee) call [Transaction](https://docs.rarebl.com/api/tx/get) with the same parameters.

## Step 4 — Get a price

[Prices](https://docs.rarebl.com/api/market/price) returns a reference price built from public exchange feeds.

```bash cURL
curl "https://api.rarebl.com/open/market/price?assets=BTC,ETH&quote=usd"
```

```js JavaScript
const { data } = await (await fetch('https://api.rarebl.com/open/market/price?assets=BTC,ETH&quote=usd')).json();
for (const p of data.prices) console.log(p.asset, p.price, p.stale);
```

```python Python
import json, urllib.request

data = json.load(urllib.request.urlopen("https://api.rarebl.com/open/market/price?assets=BTC,ETH&quote=usd"))["data"]
for p in data["prices"]:
    print(p["asset"], p["price"], p["stale"])
```

```php PHP
<?php
$data = json_decode(file_get_contents('https://api.rarebl.com/open/market/price?assets=BTC,ETH&quote=usd'), true)['data'];
foreach ($data['prices'] as $p) { echo "{$p['asset']} {$p['price']}\n"; }
```

```bash Shell
rarebl price BTC,ETH --quote usd
```

**You should see** one entry per asset (the Bitcoin entry is shortened to three sources).

```json
{ "asset": "BTC", "quote": "USD", "price": "63421.45", "change24h": "-7.1155",
  "sources": [ { "id": "binance", "pair": "BTC/USD", "price": 63449.83, "volume": 11.75039 },
               { "id": "kraken", "pair": "BTC/USD", "price": 63426.4, "volume": 5752.38744852 },
               { "id": "coinbase", "pair": "BTC/USD", "price": 63421.45, "volume": 16529.56926348 } ],
  "stale": false, "updatedAt": "2026-11-15T01:00:51.309Z" }
```

## Common errors

| Reply | What it means | What to do |
| --- | --- | --- |
| `API400` with `data.param` | A parameter is missing or malformed (unknown `chain`, bad hash or address). | Fix the parameter named in `data.param`. Do not retry unchanged. |
| `API404` | Not found: a transaction the node has not seen yet, or an unknown id. | Wait a little and ask again, or check the hash. |
| `API429` | Rate limited. | Wait `Retry-After` seconds, then retry ([Rate limits](https://docs.rarebl.com/rate-limits)). |
| `API502` | A node is unavailable, syncing or timed out. | Retry with a short back-off. |

All codes and reasons are in [Responses & codes](https://docs.rarebl.com/responses-and-codes). Each page in the [API reference](https://docs.rarebl.com/api) has a **Try It** panel that calls the live API from your browser.

## Next steps

- Credit a deposit safely: [Track a deposit until it confirms](https://docs.rarebl.com/guides/track-a-deposit).
- Send funds: [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction), or the shortcut with an SDK, [Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally).
- Get pushed events instead of polling: [Webhooks](https://docs.rarebl.com/guides/webhooks) and [Live data over WebSocket](https://docs.rarebl.com/guides/websocket).
- Learn the conventions: [Authentication](https://docs.rarebl.com/authentication), [Chains & units](https://docs.rarebl.com/chains-and-units), [Rate limits](https://docs.rarebl.com/rate-limits).

---

# Authentication

## Keyless

The Open API needs **no API key and no account**, and there is no billing. Every client is limited per IP address instead, by rate class: see [Rate limits](https://docs.rarebl.com/rate-limits).

~~~bash
curl "https://api.rarebl.com/open/fees/recommended?chain=btc"
~~~

## The reserved `X-API-KEY` header

`X-API-KEY` is reserved and **ignored** today, so you can already send it:

~~~bash
curl "https://api.rarebl.com/open/fees/recommended?chain=btc" \
  -H "X-API-KEY: your-key-when-plans-launch"
~~~

Sending the header today changes nothing: you are still limited per IP. There are no keyed plans.

## Browsers and CORS

The API is public data with no cookies. It answers with `Access-Control-Allow-Origin: *`, allows the methods `GET`, `POST` and `OPTIONS`, and allows the headers `Content-Type` and `X-API-KEY`. `OPTIONS` requests answer `204`. This means a browser app, including the Try It panel in these docs, can call the API directly. The v2 calls that add the headers `Idempotency-Key`, `X-Hook-Token` or `X-Rarebl-Accept-Risk` need those headers to be allowed by the API's CORS rules as well; if a browser call with one of them fails with a network error while the same call works from your server, that is the reason.

## What other secrets exist

The API has no accounts, but a few calls use secrets of their own, and you keep them:

- **Webhooks:** `hooks/create` returns a `manageToken` (sent as the header `X-Hook-Token`) and a `signingSecret`, both shown once. See [Webhooks](https://docs.rarebl.com/guides/webhooks).
- **Hosted signing:** requires the header `X-Rarebl-Accept-Risk: hosted-signing` and a private key in a POST body. See [Hosted signing](https://docs.rarebl.com/guides/hosted-signing). The [SDKs](https://docs.rarebl.com/sdks/python) sign locally and never send a key.

Nothing in this API uses your Rarebl login.

---

# Chains & units

The `chain` parameter selects the network. It plays the role of Etherscan's `chainid`.

## The six chains

| `chain` | Network | Symbol | Kind | Decimals | Address formats |
| --- | --- | --- | --- | --- | --- |
| `btc` | Bitcoin | BTC | UTXO | 8 | Base58 (`1…`, `3…`) and Bech32/Bech32m (`bc1…`) |
| `ltc` | Litecoin | LTC | UTXO | 8 | Base58 (`L…`, `M…`, `3…`) and Bech32 (`ltc1…`) |
| `bch` | Bitcoin Cash | BCH | UTXO | 8 | CashAddr without the prefix (`q…`, `p…`) |
| `dash` | Dash | DASH | UTXO | 8 | Base58 (`X…`, `7…`) |
| `eth` | Ethereum | ETH | Account | 18 | `0x` + 40 hex characters |
| `tron` | TRON | TRX | Account | 6 | Base58, 34 characters, starting with `T` |

ETH covers ERC-20, ERC-721 and ERC-1155 tokens. TRON covers TRC-10, TRC-20 and TRC-721.

## Units

- **Amounts are decimal strings in whole units**, exact, never floats: `"0.00131523"` BTC, `"1.5"` ETH. Parse them with a decimal or big-number type, not a floating-point number.
- Raw integer amounts, where present, are in fields named `raw…` (for example a token transfer's `rawAmount`).
- ETH gas prices (`gasPrice`, `maxFeePerGas`, `maxPriorityFeePerGas`, `baseFee`) are **Gwei** strings. `burntFee` and `fee` are ETH. `gasLimit` and `gasUsed` are integers as strings.
- TRON `fee`, `energyFee` and `netFee` are **TRX**. One TRX is 1,000,000 sun.
- Fee rates from [Recommended fees](https://docs.rarebl.com/api/fees/recommended) are **sat/vB** on UTXO chains, **Gwei** on ETH and **sun** on TRON.
- **Times** are ISO 8601 UTC strings, for example `"2026-11-14T20:31:05Z"`.
- **Unknown values are `null`**, never `""` or `0`. A `null` balance means "not known yet", not "empty".

## Hashes and addresses

- Hashes are lowercase hex. UTXO and TRON hashes have **no** `0x`; ETH hashes and addresses **do** carry `0x`.
- TRON addresses are **base58** (`T…`), not hex.
- **Bitcoin Cash** addresses are returned as **CashAddr without the prefix** (`qq…`). On input, the endpoints also accept the legacy form and the `bitcoincash:` prefix.
- [Search](https://docs.rarebl.com/api/search/query) tells you which chain a string belongs to. A legacy `1…` or `3…` address is valid on both BTC and BCH, so both are returned, Bitcoin ranked far higher; checksums are verified for every format.

## UTXO and account chains

UTXO chains (BTC, LTC, BCH, DASH) return a `utxo` object on a transaction with inputs and outputs. Account chains (ETH, TRON) return an `account` object with the sender, gas, decoded method, token transfers and logs. See [Data types](https://docs.rarebl.com/data-types).

---

# Responses & codes

Every reply, success or failure, uses the same envelope, and the HTTP status matches the code. `meta` is last and is always present.

~~~json
{ "status": 1, "code": "API200", "message": "success", "data": { }, "go": null, "meta": { "requestid": "0123456789abcdef", "notices": [] } }
~~~

| Field | Type | Meaning |
| --- | --- | --- |
| `status` | integer | `1` for success, `0` for any error. |
| `code` | string | The `API*` code below. Branch on this, not on `message`. |
| `message` | string | A human-readable message. It can change, so do not parse it. |
| `data` | object or null | The payload on success. On some errors it carries detail, such as `param`, `reason` or `detail`. |
| `go` | null | Reserved. Always `null`. |
| `meta` | object | Always present, after `go`. `meta.requestid` is the id of this request (16 hex characters, the same value as the `X-Request-Id` header). `meta.notices` is an array of advisory notices, `[]` when there are none; each notice is `{ "code", "message", "docs"? }`. |

## Codes

| Code | HTTP | Meaning |
| --- | --- | --- |
| `API200` | 200 | OK. |
| `API400` | 400 | A parameter is missing or malformed (unknown chain, bad hash, address or height). `data.param` names it. |
| `API403` | 403 | Refused by policy: hosted signing without the risk acknowledgement, or a key that does not match the inputs. `data.reason` says which. |
| `API404` | 404 | The block, transaction, address, token or webhook was not found. |
| `API405` | 405 | Method not allowed. |
| `API409` | 409 | Not available yet on this chain, or a precondition is missing. `data.reason` says why: see below. |
| `API422` | 422 | The request is well formed but the node or our checks reject it. `data.reason` gives why, and `node_rejected` also carries `data.detail`. |
| `API429` | 429 | Rate limited. A `Retry-After` header says how long to wait. See [Rate limits](https://docs.rarebl.com/rate-limits). |
| `API502` | 502 | The node is unavailable, still syncing or timed out. Retry later. |
| `API500` | 500 | Internal error. |

Every reply also carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-Request-Id`.

## Request ID

Every reply has a request id, in `meta.requestid` and in the `X-Request-Id` header (the same value). Quote it when you contact support, and log it with every error. The `meta` object is on Open API replies only; replies from the explorer backend (`explorer.rarebl.com/src/*`) have no `meta`, and webhook deliveries and WebSocket messages are unchanged.

## `API409` reasons

| `data.reason` | Meaning |
| --- | --- |
| `history_unavailable` | Address history needs the history index, which is not built for this chain yet. |
| `tx_index_pending` | ETH only: the node is still indexing old transactions. Try again later. |
| `before_history_start` | TRON only: the height is below the first block we hold (`historyFrom`, 2026-09-08). |
| `no_mempool_view` | The node has no pending-transaction view for this chain. |
| `not_watched` | BTC, LTC or BCH: the address is not watched and active yet. Start one with [Watch addresses](https://docs.rarebl.com/api/address/watch). |

## `API422` reasons

The request is valid, but it cannot be carried out.

| `data.reason` | Meaning |
| --- | --- |
| `insufficient_funds` | The inputs (or the balance) cannot cover the amount plus the fee. |
| `dust_output` | An output is below the dust limit. |
| `fee_too_low`, `fee_too_high` | The fee is below what the network relays, or above the safety limit. |
| `inputs_spent`, `inputs_unknown` | An input is already spent, or the node does not know it. |
| `bad_signature` | A signature does not verify against its digest and key. |
| `nonce_too_low` | ETH: the nonce is below the pending nonce. |
| `chain_id_mismatch` | ETH: the chain id is not 1. |
| `tx_expired` | TRON: the transaction has expired. |
| `tx_too_large` | Over the size cap: 100 kB (UTXO), 128 kB (ETH), 64 kB (TRON). |
| `node_rejected` | The node refused the transaction. `data.detail` carries its message, for example `min relay fee not met`. |

## `API403` and `API400` reasons for hosted signing

| Code and reason | Meaning |
| --- | --- |
| `API403` `risk_not_acknowledged` | The header `X-Rarebl-Accept-Risk: hosted-signing` is missing. |
| `API403` `key_mismatch` | A key does not match the address of an input it signs. |
| `API400` `plaintext_key_in_query` | A key-like value was in the query string; the request was dropped unprocessed. |

See [Hosted signing](https://docs.rarebl.com/guides/hosted-signing).

## Example: `API400`

~~~json
{ "status": 0, "code": "API400", "message": "Unknown or missing chain.", "data": { "param": "chain" }, "go": null, "meta": { "requestid": "0123456789abcdef", "notices": [] } }
~~~

## Example: `API422`

~~~json
{ "status": 0, "code": "API422", "message": "The node rejected the transaction.", "data": { "reason": "node_rejected", "detail": "min relay fee not met" }, "go": null, "meta": { "requestid": "0123456789abcdef", "notices": [] } }
~~~

## Handling errors

- Retry `API429` and `API502` with back-off. Honour `Retry-After` on `API429`.
- Do not retry `API400`: fix the request. `data.param` tells you which parameter.
- `API409` is not a failure of your request: that data or precondition is not there yet. Check `features` in [Chains](https://docs.rarebl.com/api/stats/chains), and start a watch on `not_watched`.
- `API422` means change the transaction (fund it, raise the fee, rebuild), not retry it unchanged.
- Match on `code` and `data.reason`, never on `message`.

## Conventions

Amounts are exact decimal strings in whole units, times are ISO 8601 UTC, unknown values are `null`, ETH hashes and addresses carry `0x`, TRON addresses are base58, and BCH addresses are CashAddr without the prefix. See [Chains & units](https://docs.rarebl.com/chains-and-units).

---

# Rate limits

There are **no API keys and no billing**. Every client is limited **per IP address**, and the limit depends on the kind of call: its **rate class**. Each endpoint page shows its class.

## The classes

| Class | Endpoints | Limit |
| --- | --- | --- |
| **read** | v1 reads, [Address UTXOs](https://docs.rarebl.com/api/address/utxos), [Address nonce](https://docs.rarebl.com/api/address/nonce), [Address resources](https://docs.rarebl.com/api/address/resources), [Output spend status](https://docs.rarebl.com/api/tx/outspends), [Signer key](https://docs.rarebl.com/api/tx/signer-key), [Market](https://docs.rarebl.com/api/market/price) endpoints, [Get a webhook](https://docs.rarebl.com/api/hooks/get), [Webhook deliveries](https://docs.rarebl.com/api/hooks/deliveries) | 5 per second, burst 20 (the v1 bucket) |
| **compute** | [Decode](https://docs.rarebl.com/api/tx/decode), [Estimate](https://docs.rarebl.com/api/tx/estimate), [Build](https://docs.rarebl.com/api/tx/build), [Assemble](https://docs.rarebl.com/api/tx/assemble) (without broadcast), [Validate an address](https://docs.rarebl.com/api/address/validate) | 2 per second, burst 10 |
| **write** | [Broadcast](https://docs.rarebl.com/api/tx/broadcast), [Assemble](https://docs.rarebl.com/api/tx/assemble) with `broadcast: true`, hosted [Sign](https://docs.rarebl.com/api/tx/sign), [Send](https://docs.rarebl.com/api/tx/send) and [New address](https://docs.rarebl.com/api/address/new) | 6 per minute, burst 3; 300 per day |
| **watch** | [Watch addresses](https://docs.rarebl.com/api/address/watch) | 30 per minute; 2,000 addresses per day |
| **hooks** | [Create](https://docs.rarebl.com/api/hooks/create), [Update](https://docs.rarebl.com/api/hooks/update), [Pause](https://docs.rarebl.com/api/hooks/pause), [Resume](https://docs.rarebl.com/api/hooks/resume), [Delete](https://docs.rarebl.com/api/hooks/delete), [Test](https://docs.rarebl.com/api/hooks/test), [Replay](https://docs.rarebl.com/api/hooks/replay) | 10 per minute; at most 100 active subscriptions per IP |
| **stream** | `wss://api.rarebl.com/ws` ([WebSocket stream](https://docs.rarebl.com/api/websocket)) | 3 connections per IP; 200 channel subscriptions per connection |

Each class is a separate bucket: a burst of builds does not use up your reads. The read bucket is separate from the explorer website's.

## Headers

Every reply carries:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | The size of the bucket for this call (the burst limit). |
| `X-RateLimit-Remaining` | How many requests are left in the bucket right now. |
| `X-Request-Id` | An id for the request, the same value as `meta.requestid` in the reply body. Quote it when you ask for support. |
| `Retry-After` | Only on `API429`: seconds to wait before retrying. |

Requests past a limit are answered with **`API429`** (HTTP 429).

## Handling `API429`

~~~js
async function call(url, options, tries = 3) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res.json();
    const wait = Number(res.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error('rate limited');
}
~~~

## Staying under the limits

- **Reads:** use [Live stats](https://docs.rarebl.com/api/stats/live) to watch all chains in one call; cache what does not change; poll no faster than the data changes ([Data freshness](https://docs.rarebl.com/data-freshness)). Prefer [webhooks](https://docs.rarebl.com/guides/webhooks) or the [WebSocket](https://docs.rarebl.com/guides/websocket) to polling.
- **Compute:** build once and reuse the reply; the builds an SDK makes count. Use [Estimate](https://docs.rarebl.com/api/tx/estimate) sparingly in loops.
- **Write:** this is the tight one. A broadcast is 1 of 6 per minute (burst 3) and 300 per day per IP. Batch your outputs where the chain allows, send an `Idempotency-Key` so a retry is not a second broadcast, and queue payouts instead of firing them in a burst.
- **Watch:** up to 100 addresses per call; 2,000 addresses per day. Watch only what you need. Address webhooks and WebSocket address channels on BTC, LTC and BCH watch for you, and count.
- **Hooks:** create one subscription per thing you follow and delete the ones you no longer need (100 active per IP).
- **Stream:** one connection per app, up to 3 per IP.

## Per IP, behind NAT

The limit is per IP address. Many users behind one address (an office, a mobile carrier, your own backend) share the bucket. Run heavy workloads from your own server, and cache.

## Higher limits

`X-API-KEY` is reserved. There are no keyed plans and no billing today; a key sent is ignored. See [Authentication](https://docs.rarebl.com/authentication).

---

# Pagination

Three endpoints return lists that can be paged. Each uses the style that fits its data.

| Endpoint | Style | Request | Reply |
| --- | --- | --- | --- |
| [Latest blocks](https://docs.rarebl.com/api/block/latest) | Height cursor | `before`, `limit` (1 to 25, default 10) | `items`, `next` |
| [Block](https://docs.rarebl.com/api/block/get) | Page number | `page` (default 1), `limit` (1 to 100, default 25) | `txs`, `page`, `pages`, `total` |
| [Address transactions](https://docs.rarebl.com/api/address/transactions) | Opaque cursor | `cursor`, `limit` (1 to 100, default 25) | `items`, `next` |
| [Mempool](https://docs.rarebl.com/api/tx/mempool) | None | `limit` (1 to 100, default 25) | `items` |

## Cursor on `before` (blocks)

`next` is the **lowest height** of the page. Pass it back as `before` to get the blocks below it. `next` is `null` at block 0 (on TRON, at the first block the node holds).

~~~bash
curl "https://api.rarebl.com/open/block/latest?chain=btc&limit=10"
curl "https://api.rarebl.com/open/block/latest?chain=btc&limit=10&before=975843"
~~~

## Page number (block transactions)

[Block](https://docs.rarebl.com/api/block/get) pages the block's transactions. Use `page` from 1 up to `pages`. `total` is the number of transactions in the block.

~~~bash
curl "https://api.rarebl.com/open/block/get?chain=btc&id=975851&page=2&limit=100"
~~~

## Opaque cursor (address transactions)

Pass `next` back as `cursor`, unchanged. Do not build or edit a cursor yourself. `next` is `null` on the last page.

~~~bash
curl "https://api.rarebl.com/open/address/transactions?chain=dash&address=XgNx6VFjYhSKPxXcjcPvad61DPSQhdiJDT&limit=25"
~~~

Address history is available on DASH only today: see [Coverage and limits](https://docs.rarebl.com/limits-today).

## A paging loop

~~~js
let before;
const blocks = [];
for (let page = 0; page < 5; page++) {
  const url = new URL('https://api.rarebl.com/open/block/latest');
  url.search = new URLSearchParams({ chain: 'btc', limit: '50', ...(before && { before }) });
  const { data } = await (await fetch(url)).json();
  blocks.push(...data.items);
  if (data.next === null) break;
  before = String(data.next);
}
~~~

---

# Data freshness

## Live heads: about 2 seconds

The chain heads in [Live stats](https://docs.rarebl.com/api/stats/live) (tip, mempool, fee) are cached for **at most about 2 seconds**, and the reply says when each node was last asked (`checkedAt`). Polling it once every 2 seconds is as fresh as it gets.

| Data | Freshness |
| --- | --- |
| Chain heads, mempool size, standard fee ([Live stats](https://docs.rarebl.com/api/stats/live)) | up to about 2 s old |
| Mempool list ([Mempool](https://docs.rarebl.com/api/tx/mempool)) | about 3 s, shared between callers |
| Fees ([Recommended fees](https://docs.rarebl.com/api/fees/recommended)) | about 5 to 15 s |
| Chain list ([Chains](https://docs.rarebl.com/api/stats/chains)) | about 10 s |
| Blocks, transactions and addresses deeper than the reorg depth | stable, cacheable for long |

## Confirmations

`confirmations` is the number of blocks on top of the transaction's block, counting that block. It is 0 while pending. It grows as new blocks arrive, so recompute or re-fetch rather than storing it.

## Reorg depth

Data more than the **reorg depth** below the chain tip is treated as settled and cached for long. The depths in use are:

| Chain | Reorg depth (blocks) |
| --- | --- |
| BTC, LTC, BCH, DASH | 6 |
| ETH | 64 |
| TRON | 20 |

A transaction with fewer confirmations than this can still move to another block, or disappear, in a chain reorganisation. As guidance, wait for at least the reorg depth of your chain before you treat a payment as final. The decision is yours; the table only tells you what the API considers settled.

## Chain health

A chain can be `ok`, `lagging` or `down` in [Chains](https://docs.rarebl.com/api/stats/chains) and [Live stats](https://docs.rarebl.com/api/stats/live). While a node is syncing, its `tip` is `null` and the chain is `lagging`. A node that does not answer is `down`, and calls for it answer `API502`. One slow node never delays the others.

## Be kind to the tip

Fetch what you need when the head changes instead of polling every endpoint. A simple pattern: poll [Live stats](https://docs.rarebl.com/api/stats/live) every 2 seconds, compare `tip.hash` for your chain, and call other endpoints only when it changes.

---

# Coverage and limits

Some data is not available on every chain: depending on the chain, a call can answer `API409` or `API502`, or return `null`. This page says what, and why.

## What works where

| Capability | BTC | LTC | BCH | DASH | ETH | TRON |
| --- | --- | --- | --- | --- | --- | --- |
| Chains, live heads, blocks, transactions, status | yes | yes | yes | yes | node syncing | history from 2026-09-08 |
| Address balance | `null` until watched and active | `null` until watched and active | `null` until watched and active | exact | exact | exact |
| Address transactions | from the watch time | from the watch time | from the watch time | yes | as the explorer index lands | as the explorer index lands |
| UTXOs | watch first | watch first | watch first | yes | n/a | n/a |
| Build, estimate, assemble, broadcast, decode | yes | yes | yes | yes | node syncing | yes |
| Nonce / resources | n/a | n/a | n/a | n/a | `address/nonce` | `address/resources` |
| Mempool | yes (sample) | yes (sample) | yes (sample) | yes (sample) | `API409` while no pending view | yes (up to 50) |
| Webhooks and WebSocket | yes | yes | yes | yes | node syncing | yes |

The authoritative, live version of the chain rows is `features` in [Chains](https://docs.rarebl.com/api/stats/chains).

## The reasons, and why

- **The Ethereum node is syncing.** The Ethereum node (Erigon) is still indexing, so `tx_index_pending` (`API409`) or `API502` can come from any ETH call, including build, nonce, gas and broadcast. While it syncs, the chain shows `lagging` with a `null` tip.
- **`before_history_start`: TRON history starts on 2026-09-08.** The TRON node holds blocks from that date. A block height below it answers `API409`, and `historyFrom` in [Chains](https://docs.rarebl.com/api/stats/chains) shows the date.
- **`history_unavailable`: the history index is in progress.** [Address transactions](https://docs.rarebl.com/api/address/transactions) works on DASH. On BTC, LTC and BCH it covers an address **from the time it was watched** (not its earlier history); ETH and TRON follow as the explorer index lands. Until then it answers `API409`.
- **`not_watched`: BTC, LTC and BCH addresses need a watch** for UTXOs, exact balances and activity. A new watch is `pending` while a UTXO-set bootstrap runs, then `active`. **How long the bootstrap takes depends on the deployment and the chain:** poll [Watch addresses](https://docs.rarebl.com/api/address/watch) or [Address UTXOs](https://docs.rarebl.com/api/address/utxos) until it is active.
- **`no_mempool_view`:** [Mempool](https://docs.rarebl.com/api/tx/mempool) answers this where the node has no pending transactions to show (ETH today).

## Other limits

- **Rate limits** are per IP and per rate class. Broadcast and the other write calls are the tightest: 6 per minute, burst 3, 300 per day. See [Rate limits](https://docs.rarebl.com/rate-limits).
- **Hosted signing** needs the header `X-Rarebl-Accept-Risk: hosted-signing`, and Try It is disabled for it on this site so a private key is never typed into a web page: [Hosted signing](https://docs.rarebl.com/guides/hosted-signing).
- **Webhook deliveries** come from `167.71.28.63` ([Webhooks](https://docs.rarebl.com/guides/webhooks)). Always verify the signature as well.
- **Watches** expire after 90 days without a query or webhook. Hooks: at most 100 active subscriptions per IP.
- **The stream:** 3 connections per IP, 200 channel subscriptions each.
- **Market data** is reference data from public feeds, not Rarebl trading rates.
- **Replacing a pending ETH or TRON transaction** is not covered in v2.
- Token endpoints return **known tokens** only; `holders` and `transfers` are `null` until the index exists. On TRON, TRC-10 assets are listed with null symbols.
- On Litecoin, MWEB amounts are hidden: `fee` is `null` and unresolved input values are `null`.
- Litecoin and Bitcoin Cash resolve input addresses and values on [Transaction](https://docs.rarebl.com/api/tx/get) only, for at most 50 inputs. Output `spent` flags are looked up for at most 50 outputs.
- Mempool results on UTXO chains are a **sample**; `count` is the real size.
- `X-API-KEY` is reserved: there are no keyed plans or billing.
- Not part of the Open API today: contract and logs endpoints, an RPC proxy and usage reporting.

These limits change as the index and the Ethereum node progress. The [Changelog](https://docs.rarebl.com/changelog) records each change.

---

# Data types

The shapes below are the same ones the [Rarebl Explorer](https://explorer.rarebl.com) uses, so the explorer and the API always agree. Endpoint pages refer to them by name. TypeScript notation, with `T | null` where a value can be unknown.

## ChainInfo

~~~ts
type ChainInfo = {
  id: 'btc' | 'ltc' | 'bch' | 'dash' | 'eth' | 'tron'
  name: string; symbol: string; decimals: number; kind: 'utxo' | 'account'
  status: 'ok' | 'lagging' | 'down'          // down = the node did not answer
  tip: { height: number; hash: string; time: string } | null
  historyFrom: string | null                  // earliest block time that can be shown
  features: { addressHistory: boolean; addressBalance: boolean; tokens: boolean; mempool: boolean; internalTxs: boolean }
}
~~~

## Live

~~~ts
type Live = {
  serverTime: string
  chains: {
    id: Chain
    status: 'ok' | 'lagging' | 'down'
    tip: { height: number; hash: string; time: string } | null
    mempool: { count: number | null; bytes: number | null } | null
    fee: { unit: string; standard: string | null } | null
    checkedAt: string
  }[]
}
~~~

## BlockSummary and Block

~~~ts
type BlockSummary = {
  height: number; hash: string; time: string; txCount: number
  size: number | null
  miner: string | null    // coinbase payout address / fee recipient / TRON witness
  reward: string | null   // native amount
  fees: string | null
}

type Block = BlockSummary & {
  prevHash: string | null; nextHash: string | null; confirmations: number
  details: DetailRow[]
}
~~~

On UTXO chains `reward` is all coinbase outputs and `fees` is the reward minus the subsidy (null on Dash). On ETH, `fees` is everything users paid in the block (burnt plus priority) and `reward` is the priority fees. On TRON, `reward` is null and `fees` is the TRX burnt by the block's transactions.

## TxSummary

~~~ts
type TxSummary = {
  hash: string; block: number | null; time: string | null
  status: 'success' | 'failed' | 'pending'
  from: string | null     // UTXO: the first input's address (null for coinbase)
  to: string | null       // UTXO: the first non-change output's address, best effort
  value: string           // native amount moved (UTXO: total output)
  fee: string | null
  method: string | null   // ETH/TRON: decoded method or "Transfer"; UTXO: "coinbase" or null
  inputs?: number; outputs?: number   // UTXO only
  token?: { contract: string; symbol: string | null; amount: string | null } // first token transfer, if any
}
~~~

## Tx

~~~ts
type Tx = {
  chain: Chain; hash: string; status: 'success' | 'failed' | 'pending'
  block: number | null; blockHash: string | null; time: string | null; confirmations: number
  value: string; fee: string | null
  utxo?: {
    size: number; vsize: number | null; weight: number | null; locktime: number; version: number
    rbf: boolean | null; coinbase: boolean
    inputs: { txid: string | null; vout: number | null; address: string | null; value: string | null; scriptType: string | null; sequence: number | null; coinbase: boolean }[]
    outputs: { n: number; address: string | null; value: string; scriptType: string | null; opReturn: string | null; spent: boolean | null }[]
  }
  account?: {
    from: string; to: string | null; contractCreated: string | null
    nonce: number | null; type: number | null
    gasLimit: string | null; gasUsed: string | null; gasPrice: string | null       // Gwei for ETH
    maxFeePerGas: string | null; maxPriorityFeePerGas: string | null; baseFee: string | null; burntFee: string | null
    input: string | null; methodId: string | null; methodName: string | null
    tokenTransfers: TokenTransfer[]
    logs: { index: number; address: string; topics: string[]; data: string }[]
    tron?: { contractType: string; energyUsed: number | null; energyFee: string | null; bandwidthUsed: number | null; netFee: string | null; result: string | null }
  }
  details: DetailRow[]
}

type TokenTransfer = {
  standard: 'ERC-20' | 'ERC-721' | 'ERC-1155' | 'TRC-20' | 'TRC-721' | 'TRC-10'
  contract: string; symbol: string | null; name: string | null; decimals: number | null
  from: string; to: string
  amount: string | null   // formatted with decimals when known
  rawAmount: string; tokenId: string | null; logIndex: number | null
}
~~~

On TRON, `gasLimit`, `gasUsed`, `gasPrice`, `maxFeePerGas`, `maxPriorityFeePerGas`, `baseFee`, `burntFee`, `nonce` and `type` are `null`; use the `tron` object instead.

## Address

~~~ts
type Address = {
  chain: Chain; address: string; valid: boolean
  type: string | null           // p2pkh, p2sh, p2wpkh, p2tr, cashaddr, eoa, contract, tron-account, ...
  balance: string | null        // native
  balanceStatus: 'exact' | 'index_pending'   // BTC/LTC/BCH: index_pending until the history index exists
  received: string | null; sent: string | null; txCount: number | null
  tokens: { contract: string; standard: string; symbol: string | null; name: string | null; decimals: number | null; balance: string }[]
  isContract: boolean | null
  history: { available: boolean; reason: string | null }
  details: DetailRow[]
}
~~~

## Token

~~~ts
type Token = {
  chain: 'eth' | 'tron'; contract: string; standard: string
  name: string | null; symbol: string | null; decimals: number | null; totalSupply: string | null
  holders: number | null; transfers: number | null   // null until the index exists
  details: DetailRow[]
}
~~~

## Fees

~~~ts
type Fees = {
  chain: Chain; unit: string           // "sat/vB" (UTXO), "Gwei" (ETH), "sun" (TRON)
  slow: string | null; standard: string | null; fast: string | null
  baseFee: string | null               // ETH
  details: DetailRow[]                 // TRON energy/bandwidth prices, ETH priority fee percentiles
  updatedAt: string
}
~~~

## DetailRow

Chain-specific overview rows. The API picks and orders them, and a client renders each by its `kind`.

~~~ts
type DetailRow = {
  key: string; label: string; value: string | number | boolean | null
  kind: 'text' | 'number' | 'amount' | 'hash' | 'address' | 'block' | 'tx' | 'time' | 'bytes' | 'gas' | 'percent' | 'bool' | 'code'
  unit?: string   // for example "BTC", "Gwei", "sat/vB"
  hint?: string   // tooltip text
}
~~~

---

# Track a deposit until it confirms

You have a transaction hash, for example from a customer who says "I sent it", and you want to know when it is safe to credit. You will poll [Transaction status](https://docs.rarebl.com/api/tx/status) until the transaction reaches your confirmation threshold, then confirm the amount and the address with [Transaction](https://docs.rarebl.com/api/tx/get).

## Before you start

- The `chain` the payment was sent on (`btc`, `ltc`, `bch`, `dash`, `eth` or `tron`) and the transaction hash (`id`).
- A confirmation threshold per chain. The reorg depths in [Data freshness](https://docs.rarebl.com/data-freshness) are 6 for BTC, LTC, BCH and DASH, 64 for ETH and 20 for TRON.
- Prefer being told instead of polling? Use a `tx.confirmations` [webhook](https://docs.rarebl.com/guides/webhooks) and skip to step 3.

## Step 1 — Ask for the status

```bash cURL
curl "https://api.rarebl.com/open/tx/status?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db"
```

```js JavaScript
const url = 'https://api.rarebl.com/open/tx/status?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db';
const body = await (await fetch(url)).json();
console.log(body.data.status, body.data.confirmations);
```

```python Python
import rarebl

c = rarebl.Rarebl()
data = c.status("btc", "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db")
```

```bash Shell
rarebl status --chain btc 9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db
```

**You should see** a small reply with the status and the confirmation count.

```json
{
  "status": 1, "code": "API200", "message": "success",
  "data": { "hash": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db", "status": "success", "block": 975851, "confirmations": 20, "time": "2026-11-14T22:18:52Z" },
  "go": null,
  "meta": { "requestid": "0123456789abcdef", "notices": [] }
}
```

`data.status` is one of:

| `status` | Meaning | What to do |
| --- | --- | --- |
| `pending` | Seen in the mempool, not in a block. `block` and `time` are `null`, `confirmations` is 0. | Keep polling. |
| `success` | In a block. `confirmations` counts the blocks on top, including its own. | Credit once `confirmations` reaches your threshold. |
| `failed` | Included in a block but reverted (ETH and TRON). | Do not credit. |

## Step 2 — Poll until it confirms

Poll every few seconds, back off on errors, and stop at your threshold. Heads refresh about every 2 seconds, so polling faster gains nothing.

```js JavaScript
const THRESHOLD = { btc: 6, ltc: 6, bch: 6, dash: 6, eth: 64, tron: 20 };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function waitForConfirmations(chain, id) {
  let delay = 4000;
  for (;;) {
    const res = await fetch(`https://api.rarebl.com/open/tx/status?chain=${chain}&id=${id}`);
    const body = await res.json();

    if (body.code === 'API200') {
      const { status, confirmations } = body.data;
      if (status === 'failed') return { ok: false, reason: 'reverted' };
      if (status === 'success' && confirmations >= THRESHOLD[chain]) return { ok: true, confirmations };
      delay = 4000;
    } else if (body.code === 'API429') {
      delay = Number(res.headers.get('Retry-After') ?? 1) * 1000;
    } else if (body.code === 'API404') {
      delay = 4000;                                   // not seen by our node yet: keep waiting
    } else if (body.code === 'API502' || body.code === 'API409') {
      delay = Math.min(delay * 2, 30000);             // node syncing or index pending: back off
    } else {
      throw new Error(`${body.code}: ${body.message}`);   // API400 and friends: fix the request
    }
    await sleep(delay);
  }
}
```

```python Python
import time

THRESHOLD = {"btc": 6, "ltc": 6, "bch": 6, "dash": 6, "eth": 64, "tron": 20}

def wait_for_confirmations(c, chain, txid):
    delay = 4
    while True:
        try:
            s = c.status(chain, txid)
            if s["status"] == "failed":
                return False
            if s["status"] == "success" and s["confirmations"] >= THRESHOLD[chain]:
                return True
            delay = 4
        except rarebl.ApiError as e:
            if e.code == "API400":
                raise                                   # fix the request
            delay = min(delay * 2, 30)                  # 404 not seen yet, 429, 502, 409: back off
        time.sleep(delay)
```

**You should see** the function return once the threshold is reached (or at once with a failure for a reverted transaction).

## Step 3 — Check the amount and the address

`status` only tells you the transaction is final enough. Before you credit, confirm it paid the right address and amount with [Transaction](https://docs.rarebl.com/api/tx/get).

```bash cURL
curl "https://api.rarebl.com/open/tx/get?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db"
```

- **UTXO chains:** look in `data.tx.utxo.outputs[]` for an output whose `address` is yours and whose `value` matches.
- **ETH and TRON:** check `data.tx.account.to` and `data.tx.value`, or for a token payment the matching entry in `data.tx.account.tokenTransfers[]`.
- Compare amounts as decimal strings or with a big-number type, never as floats.

**You should see** your address and the expected amount among the outputs. Only then credit the customer.

## Common errors

| Reply | What it means | What to do |
| --- | --- | --- |
| `API404` | The hash is not found yet: not seen by our node, or wrong. | Treat it as "not seen yet" for a while, then give up after a time you choose. |
| `API400` | The chain or hash is malformed. | Fix the request. |
| `API409` `tx_index_pending` | ETH only: the node is still indexing old transactions. | Retry later: see [Coverage and limits](https://docs.rarebl.com/limits-today). |
| `API429` | Polling too fast. | Wait `Retry-After`; one poll per pending deposit every few seconds is plenty. |
| `API502` | A node is unavailable or syncing. | Back off and retry. |

## Next steps

- Be pushed the events instead: [Webhooks](https://docs.rarebl.com/guides/webhooks) (`tx.confirmations`, `tx.final`).
- Find a transaction from a pasted string: [Look up any address or hash](https://docs.rarebl.com/guides/look-up-anything).
- Move the funds you received: [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses).
- Rate limits and retries: [Errors and rate limits](https://docs.rarebl.com/guides/handle-errors).

---

# Look up any address or hash

Someone pastes a string: a block height, a hash, an address, a token name, even a link from another explorer. You do not know which chain it is on, or what kind of thing it is. You will call [Search](https://docs.rarebl.com/api/search/query), read the ranked matches, and open the right endpoint.

## Before you start

- The string to look up. Nothing else is needed: no chain, no key. Send it as it was pasted: whitespace, quotes, `0x`, a `bitcoin:` payment link or an explorer link are handled.
- Search asks the nodes of the candidate chains in parallel, with a 4 second budget in total. A slow node shows up in `unavailable`, not as an error.

## Step 1 — Search

```bash cURL
curl "https://api.rarebl.com/open/search/query?q=800000"
```

```js JavaScript
const search = await (await fetch(`https://api.rarebl.com/open/search/query?q=${encodeURIComponent(q.trim())}`)).json();
if (search.code !== 'API200') throw new Error(search.message);
```

```python Python
import json, urllib.parse, urllib.request

url = "https://api.rarebl.com/open/search/query?q=" + urllib.parse.quote(q.strip())
results = json.load(urllib.request.urlopen(url))["data"]["results"]
```

**You should see** one result per match, best first. A height exists on several chains, so there are several results and `ambiguous` is `true`. Each result has a `label` ready to display, a `confidence`, and a `reason`.

```json
{
  "status": 1, "code": "API200", "message": "success",
  "data": {
    "results": [
      { "chain": "btc",  "type": "block", "id": "800000", "label": "Block 800000 · Bitcoin",      "confidence": 0.7, "reason": "Block 800000 exists on Bitcoin",      "verified": true, "path": "/btc/block/800000",  "rank": 1 },
      { "chain": "ltc",  "type": "block", "id": "800000", "label": "Block 800000 · Litecoin",     "confidence": 0.7, "reason": "Block 800000 exists on Litecoin",     "verified": true, "path": "/ltc/block/800000",  "rank": 2 },
      { "chain": "bch",  "type": "block", "id": "800000", "label": "Block 800000 · Bitcoin Cash", "confidence": 0.7, "reason": "Block 800000 exists on Bitcoin Cash", "verified": true, "path": "/bch/block/800000",  "rank": 3 },
      { "chain": "dash", "type": "block", "id": "800000", "label": "Block 800000 · Dash",         "confidence": 0.7, "reason": "Block 800000 exists on Dash",         "verified": true, "path": "/dash/block/800000", "rank": 4 }
    ],
    "best": { "chain": "btc", "type": "block", "id": "800000", "...": "the first result" },
    "ambiguous": true,
    "query": { "input": "800000", "normalized": "800000", "kind": "height", "source": "plain", "chain": null, "type": null, "payment": null },
    "suggestions": [], "unavailable": [], "mode": "full"
  },
  "go": null,
  "meta": { "requestid": "0123456789abcdef", "notices": [] }
}
```

(Shortened: `best` repeats `results[0]`.)

## Step 2 — Read what matched

| You search for | Result |
| --- | --- |
| Digits (also `#975,838`, `block 975838`) | A block height on every chain where that height exists. |
| 64 hex characters, with or without `0x` | A transaction or block hash. With `0x`, Ethereum first; without, every chain at once. |
| `0x` + 40 hex | An ETH address (a mixed-case one must pass its EIP-55 checksum): `address`, `contract` or `token`. |
| `T` + 33 base58, or 41-prefixed hex | A TRON address, or a TRC-20 contract (`token`). |
| Bech32 (`bc1…`, `ltc1…`), bech32m taproot (`bc1p…`), base58 (`1`, `3`, `L`, `M`, `X`, `7`) or CashAddr (`q…`, `p…`, `bitcoincash:`) | The matching UTXO chain or chains. |
| `USDT`, `tether`, `bitcoin`, `0xdac17f` | Known tokens and chains by name, symbol or contract prefix; a typo is tolerated. |
| An explorer link or a `bitcoin:` / `ethereum:` payment link | The identifier inside it. |

**Read `best` and `ambiguous`.** When `ambiguous` is `false` and `best` is set, open `best`. A legacy `1…` address is valid on Bitcoin and on Bitcoin Cash, but Bitcoin ranks far higher (0.92 against 0.45), so it is not ambiguous. When it is `true`, let the user pick, using `reason` and `confidence`. **No match is an empty `results` array with `API200`**, not an error: show `suggestions[].message`.

## Step 3 — Open the right endpoint

Use `type` to choose the endpoint and pass `chain` and `id` along.

| `type` | Call |
| --- | --- |
| `block` | [Block](https://docs.rarebl.com/api/block/get): `chain`, `id` |
| `tx` | [Transaction](https://docs.rarebl.com/api/tx/get): `chain`, `id` |
| `address` | [Address](https://docs.rarebl.com/api/address/balance): `chain`, `address` |
| `contract` | [Address](https://docs.rarebl.com/api/address/balance): `chain`, `address` (an address with code) |
| `token` | [Token](https://docs.rarebl.com/api/token/info): `chain`, `contract` |
| `chain` | The query named a chain (`bitcoin`): [Chains](https://docs.rarebl.com/api/stats/chains) |

```js JavaScript
const BASE = 'https://api.rarebl.com/open';

async function lookUp(q) {
  const search = await (await fetch(`${BASE}/search/query?q=${encodeURIComponent(q.trim())}`)).json();
  if (search.code !== 'API200') throw new Error(search.message);

  const { best, ambiguous, results, suggestions } = search.data;
  // One clear winner: open it. Several close ones: open them all and let the user pick.
  const wanted = best && !ambiguous ? [best] : results;
  const opened = await Promise.all(wanted.filter((r) => r.type !== 'chain').map(async (r) => {
    const call = {
      block:    `block/get?chain=${r.chain}&id=${r.id}&limit=1`,
      tx:       `tx/get?chain=${r.chain}&id=${r.id}`,
      address:  `address/balance?chain=${r.chain}&address=${r.id}`,
      contract: `address/balance?chain=${r.chain}&address=${r.id}`,
      token:    `token/info?chain=${r.chain}&contract=${r.id}`,
    }[r.type];
    return { ...r, reply: await (await fetch(`${BASE}/${call}`)).json() };
  }));
  return { opened, suggestions };
}
```

**You should see** each opened result with the reply of the matching endpoint. ETH block and transaction ids in results carry `0x`; BCH address ids are CashAddr without the prefix. On BTC, LTC and BCH an address lookup returns `balance: null` until the address is watched: see [Watch addresses](https://docs.rarebl.com/guides/watch-addresses).

## Step 4 — Handle a miss

Search tells you why nothing matched. Branch on `suggestions[].kind`, not on the text.

```json
{ "status": 1, "code": "API200", "message": "success",
  "data": { "results": [], "best": null, "ambiguous": false,
    "query": { "input": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNx", "normalized": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNx", "kind": "none", "source": "plain", "chain": null, "type": null, "payment": null },
    "suggestions": [ { "kind": "invalid_checksum", "chain": "btc", "message": "Looks like a Bitcoin address, but the checksum is wrong (a typo, or a missing or extra character). It could also be a Bitcoin Cash legacy address." } ],
    "unavailable": [], "mode": "full" },
  "go": null, "meta": { "requestid": "0123456789abcdef", "notices": [] } }
```

**You should see** an empty `results` and one suggestion. `unavailable` lists chains whose node did not answer in time: tell the user the answer may be incomplete and retry.

## Instant suggestions while typing

Send `mode=fast` with each keystroke (after a pause): it makes no node call, answers addresses, token names and contract prefixes at once, and returns heights and hashes with `verified: false`. Send the full lookup (the default mode) when the user presses Enter, or when the input is a complete number, hash or address. [Rarebl Explorer](https://docs.rarebl.com/explorer) does exactly this.

## Common errors

| Reply | What it means | What to do |
| --- | --- | --- |
| `API400` with `data.param: "q"` | `q` is missing or longer than 256 characters. | Trim the input and send at most 256 characters. |
| `API400` with `data.param: "mode"` or `"chain"` | The value is not one of the listed options. | Use `full` or `fast`; use a chain id such as `btc`. |
| Empty `results`, a `suggestion` of kind `invalid_checksum`, `wrong_length` or `testnet` | The input looks like an address but is not valid. | Show the suggestion message; ask the user to re-copy it. |
| Empty `results`, a `secret` suggestion | The input is a private or extended key. | Warn the user; the key was not searched or stored. |
| Non-empty `unavailable` | A node did not answer in time. | Show what you have and retry in a moment. |
| `API429` | Over 5 reads per second. | Wait `Retry-After`. |

## Next steps

- Ready-made pages: [Rarebl Explorer](https://docs.rarebl.com/explorer) links straight to blocks, transactions and addresses.
- Follow a transaction: [Track a deposit until it confirms](https://docs.rarebl.com/guides/track-a-deposit).
- The shared response shapes: [Data types](https://docs.rarebl.com/data-types).

---

# Watch addresses, get UTXOs and balances

A platform that takes deposits needs to know what each address holds and then move it. You will watch your deposit addresses, list their UTXOs and balances, confirm the outputs are unspent and sweep them into one wallet. Signing is covered in [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction); this guide is about finding and choosing the funds.

## Before you start

- The deposit addresses and the chain (`btc`, `ltc`, `bch`, `dash`, `eth` or `tron`).
- On **BTC, LTC and BCH** an address needs a **watch** before the API can list its UTXOs or an exact balance. **DASH** works without one (it uses its node index). ETH and TRON have no UTXOs: skip to step 6.
- A hot-wallet address to sweep into, and the signing key for the deposit addresses ([Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally)).

## Step 1 — Watch the addresses

Start a watch for up to 100 addresses per call. The API runs a UTXO-set bootstrap, then follows new blocks and the mempool.

```bash cURL
curl -X POST https://api.rarebl.com/open/address/watch -H "Content-Type: application/json" \
  -d '{"chain":"btc","addresses":["bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q"]}'
```

```js JavaScript
const res = await rarebl.watch('btc', ['bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q']);   // waits until active
```

```python Python
res = c.watch("btc", ["bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q"])
```

```php PHP
$res = $c->watch('btc', ['bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q']);
```

```bash Shell
rarebl watch --chain btc bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q
```

**You should see** each address as `pending`, then `active` once its bootstrap is done (example values).

```json
{ "watches": [ { "address": "bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q", "status": "pending", "since": "2026-11-15T01:12:07Z" } ] }
```

The watch class allows 30 calls per minute and 2,000 addresses per day. Watches expire after 90 days without a query or webhook; any read renews them. An `address.activity` [webhook](https://docs.rarebl.com/guides/webhooks) or a WebSocket `address:*` channel on BTC, LTC or BCH starts the watch for you.

## Step 2 — Wait until the watch is active

Until a watch is `active`, [Address UTXOs](https://docs.rarebl.com/api/address/utxos) answers `API409` with the reason `not_watched`. Poll every few seconds; how long the bootstrap takes depends on the chain.

```bash cURL
curl "https://api.rarebl.com/open/address/utxos?chain=btc&address=bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q"
```

**You should see** this reply while the address is not watched (or not active yet), and a normal UTXO list once it is:

```json
{ "status": 0, "code": "API409", "message": "address is not watched yet: POST address/watch first",
  "data": { "reason": "not_watched", "watch": { "chain": "btc", "address": "bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q", "endpoint": "address/watch" } }, "go": null, "meta": { "requestid": "0123456789abcdef", "notices": [] } }
```

## Step 3 — List UTXOs and the balance

Once active (or straight away on DASH), list what the address holds. Use `minConf` to ignore unconfirmed deposits.

```bash cURL
curl "https://api.rarebl.com/open/address/utxos?chain=dash&address=XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF&minConf=1"
```

```js JavaScript
const { utxos, balance } = await rarebl.utxos('dash', 'XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF', 1);
```

```python Python
r = c.utxos("dash", "XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF", min_conf=1)
```

```php PHP
$r = $c->utxos('dash', 'XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF', 1);
```

```bash Shell
rarebl utxos --chain dash XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF --min-conf 1
```

**You should see** the UTXOs plus the total (a real Dash reply):

```json
{ "utxos": [ { "txid": "1fa1b672aa5ef13127ede15aeef61c5fe3ec8565031cd826f65e6a332baefb9c", "vout": 1, "value": "4.23877346", "valueSats": 423877346,
               "height": 2572425, "confirmations": 2, "scriptPubKey": "76a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac" } ],
  "balance": "4.23877346", "balanceSats": 423877346 }
```

While an address is watched and active, [Address](https://docs.rarebl.com/api/address/balance) also returns an exact `balance` on BTC, LTC and BCH (`balanceStatus: "exact"`). Compare amounts as decimal strings or with a big-number type, never as floats.

## Step 4 — Check the outputs are unspent

Before you spend, [Output spend status](https://docs.rarebl.com/api/tx/outspends) says whether an output is spent, by what, and whether that spend is still in the mempool.

```bash cURL
curl "https://api.rarebl.com/open/tx/outspends?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db"
```

**You should see** one entry per output: `spent: false` is spendable.

```json
{ "outputs": [ { "n": 0, "spent": false, "spentBy": null, "inMempool": false }, { "n": 1, "spent": true, "spentBy": null, "inMempool": false } ] }
```

## Step 5 — Sweep with exact inputs

Build a transaction that spends exactly the UTXOs you listed, to your hot wallet, with `amount: "max"` (everything less the fee). UTXO chains allow one `to` per transaction, so build one transaction per destination.

```bash cURL
curl -X POST https://api.rarebl.com/open/tx/build -H "Content-Type: application/json" -d '{
  "chain": "dash",
  "inputs": [{"txid": "1fa1b672aa5ef13127ede15aeef61c5fe3ec8565031cd826f65e6a332baefb9c", "vout": 1}],
  "to": [{"address": "XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM", "amount": "max"}],
  "priority": "standard"
}'
```

```js JavaScript
const reply = await rarebl.build({
  chain: 'dash',
  inputs: [{ txid: '1fa1b672aa5ef13127ede15aeef61c5fe3ec8565031cd826f65e6a332baefb9c', vout: 1 }],
  to: [{ address: 'XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM', amount: 'max' }],
  priority: 'standard',
});
```

```python Python
reply = c.build({
    "chain": "dash",
    "inputs": [{"txid": "1fa1b672aa5ef13127ede15aeef61c5fe3ec8565031cd826f65e6a332baefb9c", "vout": 1}],
    "to": [{"address": "XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM", "amount": "max"}],
    "priority": "standard",
})
```

```php PHP
$reply = $c->build([
    'chain' => 'dash',
    'inputs' => [['txid' => '1fa1b672aa5ef13127ede15aeef61c5fe3ec8565031cd826f65e6a332baefb9c', 'vout' => 1]],
    'to' => [['address' => 'XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM', 'amount' => 'max']],
    'priority' => 'standard',
]);
```

**You should see** the same reply as in [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction): `unsigned` and `toSign`, with a single output that has no change. Verify, sign, assemble and broadcast it with the steps there. Inputs are verified unspent with the node, so a stale input fails with `inputs_spent` or `inputs_unknown`.

For a **payout** from a wallet use `from` instead of `inputs` and let the API choose the UTXOs; set `change` to the address that should receive the change (the default is the first `from` address).

Choose the fee:

| Option | When |
| --- | --- |
| `priority: "slow"`, `"standard"` or `"fast"` | Let the API pick from its estimator (targets of 24, 6 and 2 blocks on Bitcoin). |
| `feeRate: "12"` | A fixed rate in sat/vB. |
| `rbf: true` (the default on BTC and LTC) | Allows a later replacement if the fee turns out too low: [Stuck transactions](https://docs.rarebl.com/guides/stuck-transactions). |

Use [Recommended fees](https://docs.rarebl.com/api/fees/recommended) to see current levels and [Estimate](https://docs.rarebl.com/api/tx/estimate) to price a specific transaction. Many small inputs make a large transaction: consolidate when fees are low.

## Step 6 — ETH and TRON deposits

There are no UTXOs. Read balances with [Address](https://docs.rarebl.com/api/address/balance) and [Address tokens](https://docs.rarebl.com/api/address/tokens), the nonce with [Address nonce](https://docs.rarebl.com/api/address/nonce) (ETH) or the energy and bandwidth with [Address resources](https://docs.rarebl.com/api/address/resources) (TRON), then build a transfer from the deposit address (that address's key signs).

```bash cURL
curl "https://api.rarebl.com/open/address/resources?chain=tron&address=TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"
```

**You should see** the account's resources (a real TRON reply).

```json
{ "energy": { "limit": 0, "used": 0, "available": 0 }, "bandwidth": { "free": 600, "staked": 0, "used": 158, "available": 442 }, "frozen": [] }
```

A deposit address that holds only a token needs ETH (or TRX) to pay for the sweep: send the gas first, wait for it to confirm, then sweep. Token transfers: [Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally).

## Common errors

| Reply | What it means | What to do |
| --- | --- | --- |
| `API409` `not_watched` | BTC, LTC or BCH: the address is not watched and active. | Start a watch (step 1) and poll until `active`. |
| `API400` on `address/utxos` | ETH and TRON have no UTXOs, or the address is malformed. | Use balances and tokens instead. |
| `API422` `inputs_spent`, `inputs_unknown` | An input was spent, or the node does not know it. | Re-list the UTXOs and build again. |
| `API422` `insufficient_funds`, `dust_output` | The inputs cannot cover the amount plus the fee, or an output is too small. | Add inputs, or sweep with `amount: "max"`. |
| `API429` | Watch: 30 per minute and 2,000 addresses per day. Compute: 2 per second. | Wait `Retry-After`; watch only what you need. |

## Next steps

- Sign and send the sweep: [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction) or [Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally).
- Be told about deposits instead of polling: [Webhooks](https://docs.rarebl.com/guides/webhooks).
- Confirm one deposit: [Track a deposit until it confirms](https://docs.rarebl.com/guides/track-a-deposit).
- A sweep that does not confirm: [Stuck transactions](https://docs.rarebl.com/guides/stuck-transactions).

---

# Webhooks

Webhooks push events to your server instead of you polling: new blocks, transaction confirmations, address activity and token transfers. You will create a subscription, receive and verify the deliveries, and then manage it. There are **no accounts**: each subscription has its own management token and signing secret.

## Before you start

- A public **`https://`** endpoint on port **443 or 8443** that you control. Private, loopback, link-local and reserved IPs are refused when you create the subscription and again on every delivery, and redirects are not followed.
- A place to store two secrets for each subscription (an environment variable or a secret store).
- Optional: an SDK for verifying signatures: [JavaScript](https://docs.rarebl.com/sdks/js), [Python](https://docs.rarebl.com/sdks/python), [PHP](https://docs.rarebl.com/sdks/php) or [shell](https://docs.rarebl.com/sdks/shell).

## Step 1 — Create a subscription

Choose the event `type` and what to follow. This example follows one transaction until it is final.

```bash cURL
curl -X POST https://api.rarebl.com/open/hooks/create -H "Content-Type: application/json" -d '{
  "type": "tx.confirmations",
  "chain": "btc",
  "txid": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
  "url": "https://example.com/hooks/rarebl",
  "confirmations": 6
}'
```

```js JavaScript
const sub = await rarebl.request('POST', '/open/hooks/create', {
  type: 'tx.confirmations', chain: 'btc',
  txid: '9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db',
  url: 'https://example.com/hooks/rarebl', confirmations: 6,
});
```

```python Python
sub = c.post("/open/hooks/create", {
    "type": "tx.confirmations", "chain": "btc",
    "txid": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
    "url": "https://example.com/hooks/rarebl", "confirmations": 6,
})
```

**You should see** the subscription with its `id`, `manageToken` and `signingSecret` (the values here are examples).

```json
{ "id": "hk_3f9a2c71e0b84d56", "manageToken": "mt_7c1d0e94a2b64f3880c5e1a9d27b6f40", "signingSecret": "whsec_b81f4a9c20de7536a1c4f08e93d2b715",
  "type": "tx.confirmations", "chain": "btc", "confirmations": 6, "status": "active" }
```

**Store `manageToken` and `signingSecret` now: both are shown once.**

- `manageToken` authorizes every other hooks call. Send it in the header `X-Hook-Token`, never in a URL.
- `signingSecret` is the key of the HMAC on every delivery.

The event types:

| Type | Needs | Fires |
| --- | --- | --- |
| `block.new` | nothing | every new block, and `block.reorged` on a reorganisation |
| `tx.confirmations` | `txid` | at 0 (seen) and 1, then at each threshold up to `confirmations` (0 to 100, default 6); finally `tx.final` at the chain's reorg depth. Also `tx.dropped` (gone for 24 hours) and `tx.replaced` (RBF, with the new txid) |
| `address.activity` | `address` | in the mempool and at each confirmation threshold. BTC, LTC and BCH addresses are watched automatically |
| `token.transfer` | `address` or `contract` | ETH and TRON token transfers |

[Create a webhook](https://docs.rarebl.com/api/hooks/create) is in the hooks rate class: 10 calls per minute, at most 100 active subscriptions per IP.

## Step 2 — Receive deliveries

Rarebl `POST`s the event to your URL. Read the **raw request body**: you need the exact bytes to verify the signature.

| Header | Meaning |
| --- | --- |
| `X-Rarebl-Event-Id` | A unique event id. Use it to deduplicate. |
| `X-Rarebl-Event-Type` | For example `tx.confirmations`. |
| `X-Rarebl-Signature` | `t=<unix>,v1=<hex>`: the signature to verify. |

The body is `{id, type, chain, created, data, apiVersion: "2"}`. The contents of `data` depend on the event type; the values here are examples.

```json
{
  "id": "evt_01hx9k2p4m",
  "type": "tx.confirmations",
  "chain": "btc",
  "created": 1763160492,
  "data": { "txid": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db", "confirmations": 1, "blockHeight": 975851 },
  "apiVersion": "2"
}
```

## Step 3 — Verify the signature

`v1` is `HMAC-SHA256(signingSecret, t + "." + body)` in hex, where `t` is the timestamp from the header and `body` is the raw body. Reject a bad signature, and reject old timestamps (the SDKs allow 300 seconds).

```js JavaScript
import express from 'express';
import { webhook } from './rarebl.mjs';

const app = express();
app.post('/hooks/rarebl', express.raw({ type: '*/*' }), (req, res) => {         // the RAW body, not parsed JSON
  if (!webhook.verify(process.env.RAREBL_SIGNING_SECRET, req.body, req.get('X-Rarebl-Signature'))) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  res.sendStatus(200);                                                          // answer first, then process
  queue.push(event);
});
```

```python Python
import os, rarebl
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/rarebl")
def hook():
    if not rarebl.webhook.verify(os.environ["RAREBL_SIGNING_SECRET"], request.get_data(),
                                 request.headers.get("X-Rarebl-Signature", ""), 300):
        abort(401)
    event = request.get_json(force=True)
    queue.put(event)                                                            # process after answering
    return "", 200
```

```php PHP
<?php
require 'Rarebl.php';

$raw = file_get_contents('php://input');
$ok = Rarebl\Webhook::verify(getenv('RAREBL_SIGNING_SECRET'), $raw, $_SERVER['HTTP_X_RAREBL_SIGNATURE'] ?? '', 300);
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($raw, true);
http_response_code(200);
```

```bash Shell
rarebl verify-webhook --secret-env RAREBL_SIGNING_SECRET \
  --header "$X_RAREBL_SIGNATURE" --body-file raw-body.txt      # prints valid or invalid; exit 0 or 1
```

**You should see** your handler return 200 for a genuine delivery and 401 for a tampered one. To verify by hand in any language: split the header on `,`, read `t` and `v1`, compute the HMAC over `t + "." + rawBody`, and compare in constant time. Use the raw bytes: re-serialised JSON will not match.

## Step 4 — Handle the event

Answer **2xx within 10 seconds**, then do the real work after responding. Anything else is a failure and is retried at **1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours**, with jitter. After **20 consecutive failures** the subscription is paused.

Because of retries, deliveries can repeat and arrive out of order. So:

1. Deduplicate on `X-Rarebl-Event-Id` and make the handler idempotent.
2. Switch on `type`. Credit at `tx.confirmations` with your own threshold, treat `tx.final` as settled, and react to `tx.dropped` and `tx.replaced`.
3. Do not trust the payload alone for money: confirm with [Transaction status](https://docs.rarebl.com/api/tx/status) or [Transaction](https://docs.rarebl.com/api/tx/get).

Deliveries come from the fixed address **167.71.28.63**, so you can allow it in a firewall. Verify the signature on every request regardless.

## Step 5 — Send a test event

[Test](https://docs.rarebl.com/api/hooks/test) sends a signed sample event to your URL, so you can check your endpoint before real events arrive. Use your `manageToken` in the header.

```bash cURL
curl -X POST https://api.rarebl.com/open/hooks/test -H "Content-Type: application/json" \
  -H "X-Hook-Token: $MANAGE_TOKEN" -d '{"id": "hk_3f9a2c71e0b84d56"}'
```

**You should see** a sample delivery at your endpoint, and the attempt in [Deliveries](https://docs.rarebl.com/api/hooks/deliveries) (the last 100 attempts, with HTTP status and timing).

## Step 6 — Manage the subscription

All of these need the header `X-Hook-Token: <manageToken>` and the subscription `id`.

| Call | Use |
| --- | --- |
| [Get](https://docs.rarebl.com/api/hooks/get) | Read the subscription. |
| [Update](https://docs.rarebl.com/api/hooks/update) | Change the URL or threshold. |
| [Pause](https://docs.rarebl.com/api/hooks/pause), [Resume](https://docs.rarebl.com/api/hooks/resume) | Stop and restart deliveries. After 20 failures, fix your endpoint and resume. |
| [Replay](https://docs.rarebl.com/api/hooks/replay) | Re-send a past event by `eventId`, for example after an outage. |
| [Delete](https://docs.rarebl.com/api/hooks/delete) | Remove it when you are done. |

```bash cURL
curl -X POST https://api.rarebl.com/open/hooks/pause -H "Content-Type: application/json" \
  -H "X-Hook-Token: $MANAGE_TOKEN" -d '{"id": "hk_3f9a2c71e0b84d56"}'
curl -X POST https://api.rarebl.com/open/hooks/replay -H "Content-Type: application/json" \
  -H "X-Hook-Token: $MANAGE_TOKEN" -d '{"id": "hk_3f9a2c71e0b84d56", "eventId": "evt_01hx9k2p4m"}'
```

In **Try It** on this site, the id and token from a create call are kept in your browser and prefilled on these pages (clear them with Reset saved Try It values in the settings menu).

## Common errors

| Reply | What it means | What to do |
| --- | --- | --- |
| `API400` on create | The URL is not `https://` on 443 or 8443, or resolves to a private address. | Use a public HTTPS endpoint. |
| `API404` | The subscription id does not exist (or was deleted). | Check the id; create a new subscription. |
| An error on a manage call | The `X-Hook-Token` header is missing or is not the `manageToken` of that subscription. | Send the `manageToken` from create, in the header. |
| `API429` | The hooks class: 10 per minute. | Wait `Retry-After` seconds. |
| Many failed deliveries | Your endpoint is slow, answers non-2xx or has a bad certificate. | Check [Deliveries](https://docs.rarebl.com/api/hooks/deliveries), fix it, then Resume and Replay. |
| 100 active subscriptions | The per-IP limit. | Delete the ones you no longer need. |

## Next steps

- One subscription per thing you follow; delete it when done.
- Many addresses on BTC, LTC and BCH: an `address.activity` webhook watches them for you ([Watch addresses](https://docs.rarebl.com/guides/watch-addresses)).
- For live dashboards prefer the [WebSocket stream](https://docs.rarebl.com/guides/websocket).
- Credit deposits: [Track a deposit until it confirms](https://docs.rarebl.com/guides/track-a-deposit).

---

# Live data over WebSocket

Polling works, but a WebSocket gives you new blocks, fee changes and address activity as they happen, over one connection. You will connect to `wss://api.rarebl.com/ws`, subscribe to channels, handle events, answer the heartbeat and reconnect safely. Every channel, event and limit is in the reference: [WebSocket stream](https://docs.rarebl.com/api/websocket).

## Before you start

- A client that speaks WebSocket: a browser or Node 22+ (global `WebSocket`), or Python with `pip install websockets`.
- Nothing else: the stream is keyless and limited per IP (3 connections, 200 channel subscriptions per connection).
- For events you must not miss while offline, use [webhooks](https://docs.rarebl.com/guides/webhooks) too: a WebSocket has no replay.

## Step 1 — Connect

Open one connection and share it across your app.

```js JavaScript
const ws = new WebSocket('wss://api.rarebl.com/ws');
ws.onopen = () => console.log('connected');
```

```python Python
import asyncio, json, websockets

async def main():
    async with websockets.connect("wss://api.rarebl.com/ws") as ws:
        print("connected")
        # steps 2 and 3 go here

asyncio.run(main())
```

**You should see** the connection open. Nothing is sent until you subscribe.

## Step 2 — Subscribe to channels

Send one `subscribe` message with the channels you want.

```js JavaScript
ws.onopen = () => ws.send(JSON.stringify({
  op: 'subscribe',
  channels: ['live', 'blocks:btc', 'fees:eth', 'address:btc:bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q'],
}));
```

```python Python
await ws.send(json.dumps({
    "op": "subscribe",
    "channels": ["live", "blocks:btc", "fees:eth", "address:btc:bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q"],
}))
```

**You should see** a confirmation listing what was accepted and, for anything refused, a `rejected` entry with a reason.

```json
{ "op": "subscribed", "channels": ["live", "blocks:btc", "fees:eth", "address:btc:bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q"], "rejected": [] }
```

The channels:

| Channel | What you get |
| --- | --- |
| `live` | The heads of every chain (the latest is replayed when you subscribe). |
| `blocks:<chain>` | New blocks of a chain, and reorganisations. |
| `fees:<chain>` | Fee updates. |
| `address:<chain>:<address>` | Activity on an address. On BTC, LTC and BCH the address is **watched automatically**. |
| `tx:<chain>:<txid>` | Progress of one transaction. |
| `token:<chain>:<address>`, `token:<chain>:c:<contract>` | Token transfers of an address or a contract on `eth` or `tron`. |

## Step 3 — Handle events and the heartbeat

Events arrive as `{"channel","type","data","ts"}`. The server sends `{"op":"ping"}` every **20 seconds**: answer `{"op":"pong"}` (any message you send counts as life; after 70 seconds of silence the socket is closed).

```js JavaScript
ws.onmessage = (event) => {
  const m = JSON.parse(event.data);
  if (m.op === 'ping') return ws.send(JSON.stringify({ op: 'pong' }));
  if (m.op === 'error') return console.error(m.code, m.message);
  if (m.channel) queue.push(m);                    // hand work to a queue: never block this handler
};
```

```python Python
async for raw in ws:
    m = json.loads(raw)
    if m.get("op") == "ping":
        await ws.send(json.dumps({"op": "pong"}))
    elif m.get("op") == "error":
        print(m["code"], m["message"])
    elif "channel" in m:
        queue.put_nowait(m)                         # hand work to a queue: never block this loop
```

**You should see** events such as a new block (example values below; the shape of `data` follows [Data types](https://docs.rarebl.com/data-types) and the webhook events in [Webhooks](https://docs.rarebl.com/guides/webhooks)). Event types: `block.new`, `block.reorged`, `address.activity`, `tx.confirmations`, `tx.final`, `tx.dropped`, `tx.replaced`, `token.transfer`, `live` and `fees`.

```json
{ "channel": "blocks:btc", "type": "block.new", "data": { "height": 975870, "hash": "…" }, "ts": "2026-11-15T01:09:33Z" }
```

To stop a channel, send `{"op":"unsubscribe","channels":["fees:eth"]}`.

## Step 4 — Reconnect with back-off

Subscriptions do not survive a dropped connection, so resubscribe on every reconnect. Back off, and add jitter if you run many clients.

```js JavaScript
const CHANNELS = ['live', 'blocks:btc'];
let delay = 1000;

function connect() {
  const ws = new WebSocket('wss://api.rarebl.com/ws');
  ws.onopen = () => { delay = 1000; ws.send(JSON.stringify({ op: 'subscribe', channels: CHANNELS })); };
  ws.onmessage = onMessage;
  ws.onclose = () => { setTimeout(connect, delay + Math.random() * 500); delay = Math.min(delay * 2, 30000); };
}
connect();
```

```python Python
async def run():
    delay = 1
    while True:
        try:
            async with websockets.connect("wss://api.rarebl.com/ws") as ws:
                delay = 1
                await ws.send(json.dumps({"op": "subscribe", "channels": CHANNELS}))
                async for raw in ws:
                    handle(json.loads(raw), ws)
        except (OSError, websockets.ConnectionClosed):
            await asyncio.sleep(delay)
            delay = min(delay * 2, 30)
```

**You should see** the stream resume after a network blip. While you were disconnected you may have missed events: catch up with [Live stats](https://docs.rarebl.com/api/stats/live), [Block](https://docs.rarebl.com/api/block/get) or [Transaction status](https://docs.rarebl.com/api/tx/status).

## Step 5 — Stay within the limits

| Limit | Value |
| --- | --- |
| Connections | 3 per IP. Share one connection across your app; the 4th is closed (code 1008). |
| Subscriptions | 200 channels per connection. |
| Slow clients | A client with 256 unacknowledged messages is closed (code 1013). Do not block the handler. |
| Client messages | More than 60 in 10 seconds closes the socket (1008); incoming frames are capped at 16 kB. |
| Heartbeat | The server pings every 20 s; answer `{"op":"pong"}`. |
| Watches | Address channels on BTC, LTC and BCH watch the address, which counts against 2,000 addresses per day ([Rate limits](https://docs.rarebl.com/rate-limits)). |

## WebSocket or webhook?

| | WebSocket | Webhook |
| --- | --- | --- |
| Direction | You connect to Rarebl | Rarebl calls your server |
| Best for | Dashboards, wallets in a browser, live fees | Servers that must not miss an event |
| Delivery guarantee | None: events while disconnected are missed | Retried for 24 hours, up to 20 failures |
| Setup | One connection | A public HTTPS endpoint |

## Common errors

| Symptom | What it means | What to do |
| --- | --- | --- |
| `{"op":"error","code","message"}` | The server refused a message. | Match on `code`, fix the message. |
| `rejected` entries in `subscribed` | A channel was invalid or over the limit. | Check the channel name and your count. |
| Closed with 1008 | A fourth connection, or too many messages. | Reuse one connection; slow down. |
| Closed with 1013 | You were too slow to read. | Process events on a queue and reconnect. |
| Closed after 70 s silent | The pong was missing. | Answer every `ping` with `pong`. |

## Next steps

- Reference: [WebSocket stream](https://docs.rarebl.com/api/websocket).
- Server-to-server delivery with retries: [Webhooks](https://docs.rarebl.com/guides/webhooks).
- Poll instead: [Live stats](https://docs.rarebl.com/api/stats/live) and [Market data and fees](https://docs.rarebl.com/guides/market-data).

---

# Market data and fees

Show a fiat value next to a crypto amount, draw a price chart and display the current network fee. You will use the market endpoints for **reference prices and FX rates** aggregated from public sources, and [Live stats](https://docs.rarebl.com/api/stats/live) and [Recommended fees](https://docs.rarebl.com/api/fees/recommended) for fees.

> **These are reference prices, not Rarebl trading rates.** Rarebl does not guarantee that you can buy or sell at these prices, and they are not an offer. Do not use them to settle a trade.

## Before you start

- Nothing to install. These are read-class calls: 5 per second, burst 20 per IP, so cache results for a few seconds instead of calling per page view.
- A decimal type for money. Chain amounts are exact decimal strings and `price` is one too.

## Step 1 — Get a price

[Prices](https://docs.rarebl.com/api/market/price) takes the **median of the fresh sources** and excludes any source more than 2% from the median. Quotes are `usd`, `eur`, `gbp`, `ghs` and `ngn` (the last four are derived from the dollar price through the FX rates).

```bash cURL
curl "https://api.rarebl.com/open/market/price?assets=BTC,ETH&quote=usd"
```

```js JavaScript
const { prices } = await rarebl.marketPrice(['BTC', 'ETH'], 'usd');       // or fetch the URL above
```

```python Python
prices = c.price(["BTC", "ETH"], "usd")
```

```php PHP
$prices = $c->price(['BTC', 'ETH'], 'usd');
```

```bash Shell
rarebl price BTC,ETH --quote usd
```

**You should see** one entry per asset (the Bitcoin entry shortened to three sources).

```json
{ "asset": "BTC", "quote": "USD", "price": "63421.45", "change24h": "-7.1155",
  "sources": [ { "id": "binance", "pair": "BTC/USD", "price": 63449.83, "volume": 11.75039 },
               { "id": "kraken", "pair": "BTC/USD", "price": 63426.4, "volume": 5752.38744852 },
               { "id": "coinbase", "pair": "BTC/USD", "price": 63421.45, "volume": 16529.56926348 } ],
  "stale": false, "updatedAt": "2026-11-15T01:00:51.309Z" }
```

| Field | Meaning |
| --- | --- |
| `asset`, `quote` | The symbol and the quote currency (upper case in replies). |
| `price` | A decimal string. |
| `change24h` | The percent change over 24 hours as a string such as `"-1.25"`, or `null`. |
| `sources` | The exchanges that went into the median. An entry with `excluded: true` was an outlier; `usdtProxy: true` marks a USDT market used because fewer than two USD or USDC markets were fresh. |
| `stale` | True when there were not enough fresh sources, or two sources disagree by more than 4%. Show the price with a warning, or hide it. |
| `updatedAt` | When it was computed. |

## Step 2 — Convert with FX

[FX](https://docs.rarebl.com/api/market/fx) returns currency rates against a base, with the source and update time.

```bash cURL
curl "https://api.rarebl.com/open/market/fx?base=usd&quotes=ghs,ngn"
```

**You should see** the rates keyed by quote currency.

```json
{ "rates": { "GHS": "11.747527", "NGN": "1352.072165" }, "source": "er-api", "updatedAt": "2026-11-15T00:37:02.017Z" }
```

## Step 3 — Draw a chart

[History](https://docs.rarebl.com/api/market/history) returns OHLC candles (`1m`, `1h` or `1d`; at most 1,000 per call). Use `from` and `to` to page through longer ranges. Candle `volume` is `null`, and a fiat quote other than USD converts candles at the current FX rate, which is an approximation.

```bash cURL
curl "https://api.rarebl.com/open/market/history?asset=BTC&quote=USD&interval=1h&from=1763161200"
```

**You should see** candles, oldest first.

```json
{ "candles": [
  { "ts": "2026-11-14T23:00:00.000Z", "open": "64136.4", "high": "64174.2", "low": "64068.4", "close": "64139.5", "volume": null },
  { "ts": "2026-11-15T00:00:00.000Z", "open": "64123.32", "high": "64469.5", "low": "63430.38", "close": "63478.34", "volume": null }
] }
```

## Step 4 — Show the network fee

[Live stats](https://docs.rarebl.com/api/stats/live) gives every chain's head, mempool and fee in one call. It refreshes about every 2 seconds, so poll no faster than that.

```bash cURL
curl "https://api.rarebl.com/open/stats/live"
```

```js JavaScript
async function refresh() {
  const { data } = await (await fetch('https://api.rarebl.com/open/stats/live')).json();
  for (const c of data.chains) {
    const el = document.querySelector(`[data-fee="${c.id}"]`);
    el.textContent = c.fee?.standard != null ? `${c.fee.standard} ${c.fee.unit}` : 'unavailable';
  }
}
refresh();
setInterval(refresh, 2000);
```

**You should see** an entry per chain with a `fee`. A chain that is `lagging` or `down` has `fee: null`: show "unavailable" rather than a number.

```json
{ "id": "btc", "status": "ok", "tip": { "height": 975869, "hash": "000000000000000000018a26062659ab25520a26b803d3e4ec9568a85c3f4235", "time": "2026-11-15T01:00:09Z" },
  "mempool": { "count": 55876, "bytes": 22836693 }, "fee": { "unit": "sat/vB", "standard": "0.12" }, "checkedAt": "2026-11-15T01:01:02Z" }
```

When the user can choose a speed, call [Recommended fees](https://docs.rarebl.com/api/fees/recommended) for that chain.

```bash cURL
curl "https://api.rarebl.com/open/fees/recommended?chain=btc"
```

**You should see** slow, standard and fast rates and their unit (`details` omitted here).

```json
{ "chain": "btc", "unit": "sat/vB", "slow": "0.12", "standard": "0.12", "fast": "0.12", "baseFee": null, "updatedAt": "2026-11-15T01:01:02Z" }
```

The unit depends on the chain, so always show it next to the number:

- **UTXO chains:** `sat/vB`. The three speeds map to estimator targets of 24, 6 and 2 blocks on Bitcoin. Bitcoin Cash has no estimator on its node, so all three values are the relay minimum.
- **ETH:** `Gwei`, with `baseFee` set and priority fee percentiles in `details`.
- **TRON:** `sun`; `standard` is the energy price in sun per energy unit, and `slow` and `fast` are `null`.

For a UTXO transaction the fee is about `rate × vsize`: a 142 vB transaction at 1 sat/vB costs about 142 sats.

## Step 5 — Show a fiat value, with attribution

```js JavaScript
const { data } = await (await fetch('https://api.rarebl.com/open/market/price?assets=BTC&quote=GHS')).json();
const p = data.prices[0];
if (!p.stale) {
  const fiat = (Number(balanceBtc) * Number(p.price)).toFixed(2);       // for display only: use a decimal library if you store it
  label.textContent = `${fiat} GHS · reference price`;
}
```

- Say where the number comes from: show "Reference price from public exchange feeds via Rarebl" (or similar) near it, and state that it is not a trading rate.
- Exchange data comes from Binance, Coinbase Exchange, Kraken, Bitstamp, Bitfinex, OKX, Bybit and KuCoin; FX from ExchangeRate-API (open.er-api.com) and the ECB.
- Check `stale` and `updatedAt`, and decide what your product does when the data is old.
- Map a token contract to a price symbol with [Assets](https://docs.rarebl.com/api/market/assets) (for example USDT on `eth` and on `tron`), then ask for that symbol. [Tickers](https://docs.rarebl.com/api/market/tickers) lists the individual exchange tickers behind a price.

## Common errors

| Reply | What it means | What to do |
| --- | --- | --- |
| `API400` with `data.param` | An unknown asset, quote or interval, or a bad range. | Check the symbol against [Assets](https://docs.rarebl.com/api/market/assets). |
| `API429` | More than 5 reads per second. | Cache for a few seconds and honour `Retry-After`. |
| `stale: true` in a price | Not enough fresh sources, or they disagree. | Show a warning or hide the price. |
| `fee: null` in live stats | That chain is `lagging` or `down`. | Show "unavailable" and keep the last value. |
| `API502` | A node is unavailable. | Keep the last value and retry after a longer pause. |

## Next steps

- Decide a fee for a payment: [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction) and [Estimate](https://docs.rarebl.com/api/tx/estimate).
- Get fee updates pushed: [Live data over WebSocket](https://docs.rarebl.com/guides/websocket) (`fees:<chain>`).
- Errors and retries: [Errors and rate limits](https://docs.rarebl.com/guides/handle-errors).

---

# Send a transaction

Send a payment on any chain in four calls: **build** the transaction, **verify** what the API returned, **sign** the digests on your machine, then **assemble and broadcast**. Your private key never leaves your code. The examples use a real Dash build; the flow is identical on BTC, LTC, BCH, ETH and TRON.

If you only want the shortcut, an SDK does all four steps in one `transfer()` call: [Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally).

## Before you start

- An address with funds on the chain, and its private key kept locally (an environment variable, a file or an HSM, never in source control).
- BTC, LTC and BCH senders must be **watched** first: [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses). DASH, ETH and TRON need no watch.
- An SDK ([JavaScript](https://docs.rarebl.com/sdks/js), [Python](https://docs.rarebl.com/sdks/python), [PHP](https://docs.rarebl.com/sdks/php) or [shell](https://docs.rarebl.com/sdks/shell)), or your own secp256k1 signing code.
- A small test amount for the first run. A broadcast cannot be undone.

## Step 1 — Build the transaction

Ask the API for an unsigned transaction. It picks the inputs, adds change and prices the fee; you choose `priority` (`slow`, `standard`, `fast`) or a fixed `feeRate`.

```bash cURL
curl -X POST https://api.rarebl.com/open/tx/build -H "Content-Type: application/json" -d '{
  "chain": "dash",
  "from": ["XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF"],
  "to": [{"address": "XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM", "amount": "0.01"}],
  "priority": "standard"
}'
```

```js JavaScript
import { Rarebl } from './rarebl.mjs';

const rarebl = new Rarebl();                                   // https://api.rarebl.com
const reply = await rarebl.build({
  chain: 'dash',
  from: ['XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF'],
  to: [{ address: 'XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM', amount: '0.01' }],
  priority: 'standard',
});
```

```python Python
import rarebl

c = rarebl.Rarebl()                                            # https://api.rarebl.com
reply = c.build({
    "chain": "dash",
    "from": ["XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF"],
    "to": [{"address": "XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM", "amount": "0.01"}],
    "priority": "standard",
})
```

```php PHP
<?php
require 'Rarebl.php';

$c = new Rarebl\Rarebl();                                      // https://api.rarebl.com
$reply = $c->build([
    'chain' => 'dash',
    'from' => ['XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF'],
    'to' => [['address' => 'XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM', 'amount' => '0.01']],
    'priority' => 'standard',
]);
```

```bash Shell
rarebl build --chain dash --from XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF \
  --to XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM --amount 0.01 --priority standard > build.json
```

**You should see** the `unsigned` transaction, the `toSign` digests and an `expiresAt` (hex shortened here).

```json
{
  "unsigned": {
    "chain": "dash", "format": "utxo-v1",
    "tx": "0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a0100000000ffffffff02…00000000",
    "inputs": [ { "txid": "7a08e8423f8f4bfe21b0569547b6315f16a94b42d72be5d972a86e0385619f13", "vout": 1, "address": "XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF",
                  "value": "4.23879226", "valueSats": "423879226", "scriptType": "p2pkh", "sequence": 4294967295,
                  "prevTx": "0200000001…00000000" } ],
    "outputs": [ { "address": "XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM", "value": "0.01", "valueSats": "1000000", "change": false },
                 { "address": "XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF", "value": "4.22879", "valueSats": "422879000", "change": true } ],
    "fee": "0.00000226", "feeSats": "226", "vsize": 226, "feeRate": "1"
  },
  "toSign": [ { "index": 0, "address": "XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF", "digest": "60f09e680a8d4d7442ec09e2e89181c568f596c6200c6a2d2f4aa15a4a8fc6b1",
                "algorithm": "ecdsa-secp256k1", "sighashType": 1, "scriptType": "p2pkh" } ],
  "expiresAt": "2026-11-15T00:31:27Z"
}
```

On legacy p2pkh inputs (BTC, LTC, DASH) each input also carries `prevTx`, the raw previous transaction (hex shortened here). The signature of such an input does not commit to its amount, so the SDKs read the amount from `prevTx` after checking that it hashes to the input's `txid`.

ETH and TRON take a single `from` and `to` plus an optional `token`; their `unsigned.format` is `eth-1559-v1` or `tron-v1`. See [Build](https://docs.rarebl.com/api/tx/build) for every field.

## Step 2 — Verify the reply

A digest is 32 bytes: you cannot see what it commits to. If anything between you and the API returned a transaction that pays someone else, your valid signature would authorize it. So check before you sign:

1. **Recompute each digest** from `unsigned` (rules at the end of this page).
2. **Check the outputs**: the recipient and amount are what you asked for, and any change goes back to you.
3. **Check the fee** against a cap you set.

The SDKs do all three, and signing refuses to run without an expectation: you must say who is paid. Pass the recipient and amount, and a fee cap if the defaults do not suit you.

```js JavaScript
import { describeBuild } from './rarebl.mjs';

const expect = { to: [{ address: 'XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM', amount: '0.01' }], maxFeeSats: 5000 };
console.log(describeBuild(reply, { expect }));      // what is really being paid; throws VerifyError on a mismatch
```

```python Python
expect = {"to": {"address": "XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM", "amount": "0.01"}, "maxFeeSats": 5000}
rarebl.verify_build(reply, expect=expect)             # raises VerifyError on a mismatch
```

```php PHP
$expect = ['to' => ['address' => 'XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM', 'amount' => '0.01'], 'maxFeeSats' => 5000];
Rarebl\Signer::verifyBuild($reply, null, $expect);    // throws VerifyException on a mismatch
```

The shell tool verifies inside `rarebl sign` (next step) when you pass `--expect-to` and `--expect-amount`.

**You should see** no error. A mismatch raises `VerifyError` before anything is signed. Never turn verification off.

Even when `expect` names no fee cap, the SDKs apply one:

| Chain | Default cap | Override in `expect` |
| --- | --- | --- |
| BTC, LTC | 1000 sat/vB | `maxFeeRate`, or an absolute `maxFee` / `maxFeeSats` |
| BCH, DASH | 50 sat/byte | `maxFeeRate`, or an absolute `maxFee` / `maxFeeSats` |
| ETH | `maxFeePerGas` at most 500 gwei, total fee at most 0.05 ETH, tip at most max(5 gwei, `maxFeePerGas` / 2) | `maxFeePerGas`, `maxPriorityFeePerGas` (wei), `maxFee` |
| TRON | `feeLimit` at most 150 TRX | `maxFeeLimit` (sun) |

They also refuse a UTXO transaction with a non-zero locktime (unless `allowLocktime: true`), a version other than 1 or 2, a repeated input, or a sighash type other than SIGHASH_ALL (`0x41`, with FORKID, is accepted on BCH only).

## Step 3 — Sign the digests locally

Sign each digest with the key of the input's `address`. The SDK verifies again, signs and returns one signature per digest. ECDSA is RFC 6979 deterministic and low-S; Schnorr (p2tr) uses fresh random auxiliary data unless you pass `deterministic` for reproducible output.

```js JavaScript
import { signBuild } from './rarebl.mjs';

const signatures = signBuild(reply, [process.env.DASH_KEY], { expect });          // expect is required
```

```python Python
import os

signatures = rarebl.sign_build(reply, os.environ["DASH_KEY"], expect=expect)   # expect is required
```

```php PHP
$signatures = Rarebl\Signer::signBuild($reply, getenv('DASH_KEY'), ['expect' => $expect]);   // expect is required
```

```bash Shell
rarebl sign build.json --key-env DASH_KEY \
  --expect-to XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM --expect-amount 0.01 > sigs.json
```

**You should see** one `{index, signature, publicKey}` per digest (the values here are examples).

```json
[ { "index": 0, "signature": "3044022047ac8e87…2f0220217f36a4…dcb01", "publicKey": "03ad1d8e89212f0b92c74d23bb710c00662ad1470198ac48c43f7d6f93a2a26873" } ]
```

If you sign without an SDK (an HSM, another language), produce the signature form for the chain: DER plus the sighash byte for UTXO ECDSA, 64 or 65 bytes for Schnorr (p2tr), and 65 bytes `r ‖ s ‖ v` for ETH and TRON.

## Step 4 — Assemble the signed transaction

Send `unsigned` back unchanged with your signatures. The API checks every signature against its digest and key, and that the key matches the input address, then returns the signed transaction. Leave `broadcast` false for now so you can inspect it.

```bash cURL
curl -X POST https://api.rarebl.com/open/tx/assemble -H "Content-Type: application/json" -d '{
  "unsigned": { …the unsigned object from step 1… },
  "signatures": [ { "index": 0, "signature": "3044…01", "publicKey": "03ad…6873" } ],
  "broadcast": false
}'
```

```js JavaScript
const { signed } = await rarebl.assemble(reply.unsigned, signatures, { broadcast: false });
```

```python Python
signed = c.assemble(reply["unsigned"], signatures, broadcast=False)["signed"]
```

```php PHP
$signed = $c->assemble($reply['unsigned'], $signatures, false)['signed'];
```

```bash Shell
rarebl assemble build.json sigs.json > signed.json
```

**You should see** `signed` with the transaction hex and its `txid`, and `broadcast: null`.

```json
{ "signed": { "chain": "dash", "hex": "0200000001139f…88ac00000000", "txid": "…" }, "broadcast": null }
```

Optional: decode the hex with [Decode](https://docs.rarebl.com/api/tx/decode) to see the outputs one more time before you send.

## Step 5 — Broadcast

Send it with [Broadcast](https://docs.rarebl.com/api/tx/broadcast), with an `Idempotency-Key` so a retry can never send twice (the same key, or the same txid, within 24 hours returns the first result). Or set `broadcast: true` in step 4 to do both in one call.

```bash cURL
curl -X POST https://api.rarebl.com/open/tx/broadcast -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-11-15-0001" \
  -d '{"chain": "dash", "hex": "0200000001139f…88ac00000000"}'
```

```js JavaScript
const result = await rarebl.broadcast('dash', signed.hex, { idempotencyKey: 'payout-2026-11-15-0001' });
```

```python Python
result = c.broadcast("dash", signed["hex"], idempotency_key="payout-2026-11-15-0001")
```

```php PHP
$result = $c->broadcast('dash', $signed['hex'], 'payout-2026-11-15-0001');
```

```bash Shell
rarebl assemble build.json sigs.json --broadcast        # assemble and broadcast in one step
```

**You should see** the txid and `accepted: true`.

```json
{ "txid": "…", "accepted": true, "alreadyKnown": false }
```

Broadcast is in the **write** rate class: 6 per minute (burst 3) and 300 per day per IP, so queue payouts instead of firing them in a burst. UTXO broadcasts run the node's `testmempoolaccept` first at its default maximum fee rate; you may lower it with `maxFeeRate` (sat/vB) but never raise it.

## Step 6 — Wait for confirmation

Follow the transaction with [Transaction status](https://docs.rarebl.com/api/tx/status), or let a `tx.confirmations` [webhook](https://docs.rarebl.com/guides/webhooks) tell you. Confirmation thresholds: [Data freshness](https://docs.rarebl.com/data-freshness).

```bash cURL
curl "https://api.rarebl.com/open/tx/status?chain=dash&id=<txid>"
```

**You should see** `status: "pending"` with `confirmations: 0`, then `"success"` once it is in a block. If it stays pending for a long time: [Stuck transactions](https://docs.rarebl.com/guides/stuck-transactions).

## Local or hosted signing

Everything above signs on your side. Rarebl also offers hosted signing, where `tx/sign` and `tx/send` sign for you with a private key you send in the request.

| | Sign locally (this guide, SDKs) | Hosted signing |
| --- | --- | --- |
| Where the key is | Only on your machine | Sent to Rarebl over TLS for each request, in an envelope that is single-use and expires within 300 seconds |
| Who signs | Your code or the SDK | Rarebl's signer, in memory |
| Checking the digests | You, with `verifyBuild` and `expect` | The signer signs only what the envelope names: the digests (`tx/sign`) or the recipients and amounts (`tx/send`) |
| Extra requirement | None | Header `X-Rarebl-Accept-Risk: hosted-signing` |
| Rate class | Build and assemble are compute; broadcast is write | Write |

Signing locally keeps keys on your side. Hosted signing is covered in [Hosted signing](https://docs.rarebl.com/guides/hosted-signing); the SDKs are on the [JavaScript](https://docs.rarebl.com/sdks/js), [Python](https://docs.rarebl.com/sdks/python), [PHP](https://docs.rarebl.com/sdks/php) and [shell](https://docs.rarebl.com/sdks/shell) pages.

## How the digests are made

The SDKs implement these rules and check them in step 2. If you sign by hand, so must you.

| Script type | Digest | Algorithm |
| --- | --- | --- |
| p2pkh (BTC, LTC, DASH) | legacy sighash, SIGHASH_ALL (1) | `ecdsa-secp256k1` |
| p2wpkh, p2sh-p2wpkh (BTC, LTC) | BIP143 | `ecdsa-secp256k1` |
| p2tr key path (BTC) | BIP341, SIGHASH_DEFAULT (0) | `schnorr-bip340` |
| BCH | BIP143-style with FORKID, sighashType `0x41` | `ecdsa-secp256k1` |
| ETH | `keccak256(0x02 ‖ rlp([chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit, to, value, data, accessList]))` | `ecdsa-secp256k1-recoverable` |
| TRON | `txID` = sha256 of the `raw_data` protobuf bytes | `ecdsa-secp256k1-recoverable` |

For ETH also check that `chainId` is 1 and that `to`, `value` and `data` are what you meant (a token transfer calls `a9059cbb` with the recipient and raw amount). For TRON check that `sha256(raw_data_hex)` equals `txID`.

## Common errors

| Reason | What it means | What to do |
| --- | --- | --- |
| `API409` `not_watched` | BTC, LTC or BCH: the `from` address is not watched and active. | [Watch it](https://docs.rarebl.com/guides/watch-addresses) and wait for `active`. |
| `API422` `insufficient_funds` | The inputs cannot cover the amount plus the fee. | Fund the address, lower the amount or use `amount: "max"`. |
| `API422` `dust_output` | An output is below the dust limit. | Raise the amount or drop the tiny output. |
| `API422` `inputs_spent`, `inputs_unknown` | An input is already spent, or the node does not know it. | Check [Output spend status](https://docs.rarebl.com/api/tx/outspends) and build again. |
| `API422` `bad_signature` | A signature does not verify against its digest and key. | Sign the digest from this build, with the right key. |
| `API403` `key_mismatch` | The key does not derive the input's address. | Use the key of the address in `toSign`. |
| `VerifyError`: missing `prevTx` or wrong amount | A legacy p2pkh input (BTC, LTC, DASH) has no `prevTx`, or its `prevTx` does not hash to the input's `txid` or does not carry the amount `tx/build` stated. Nothing is signed. | Build again and use the reply as it is. If you pass your own, give `prevTxs` (`prev_txs`) as raw transactions keyed by txid. |
| `VerifyError`: fee above the cap | The fee is above the default or the `expect` cap. | Lower `feeRate` or `priority`, or raise the cap in `expect` if the fee is intended. |
| `InputError`: `expect` required | Signing was called without `expect` (or without `expect.to`). | Pass the recipient and amount. `unsafeNoExpect` (`--unsafe-no-expect`) exists for signing without pinning the recipient; the fee caps still apply. |
| `API422` `fee_too_low`, `fee_too_high` | The fee is below what the network relays, or above the safety limit. | Change `feeRate` or `priority`. |
| `API422` `nonce_too_low`, `chain_id_mismatch` | ETH: the nonce is behind the pending nonce, or the chain id is not 1. | Build again. |
| `API422` `tx_expired` | TRON: the transaction expired before it was broadcast. | Build, sign and broadcast again. |
| `API422` `node_rejected` | The node refused it; `data.detail` has its message. | Read `detail`, for example `min relay fee not met`. |
| `API429` | A rate limit. | Wait `Retry-After` seconds. |

The full list is in [Responses & codes](https://docs.rarebl.com/responses-and-codes).

## Next steps

- One call instead of four: [Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally), including ETH and USDT on TRON.
- Move many deposits: [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses).
- A payment that does not confirm: [Stuck transactions](https://docs.rarebl.com/guides/stuck-transactions).
- Handling failures in production: [Errors and rate limits](https://docs.rarebl.com/guides/handle-errors).

---

# Sign locally with the SDKs

The SDKs turn the whole [send flow](https://docs.rarebl.com/guides/send-a-transaction) into one `transfer()` call. They ask the API for UTXOs, nonce and fees, then build, verify and sign **on your machine**, and ask the API to broadcast. Your private key is never sent over the network. You will download an SDK, load a key, and send BTC, ETH or USDT on TRON.

## Before you start

- An address with a small balance on the chain you want to try, and its private key (hex or WIF) in an environment variable or a file.
- For ETH and TRON, a little ETH or TRX for fees, even when you send a token.
- JavaScript (Node 18+ or a browser), Python 3.9+, PHP 8.1+ with `ext-gmp`, or bash with `curl`, `jq` and Python 3.9+.
- Run signing on a machine you control. The pure-language crypto is correct but not constant-time, so avoid shared hosting.

## Step 1 — Download the SDK

Download the single file and check its SHA-256 against `https://docs.rarebl.com/sdk/SHA256SUMS`. Each SDK page lists the checksum: [JavaScript](https://docs.rarebl.com/sdks/js), [Python](https://docs.rarebl.com/sdks/python), [PHP](https://docs.rarebl.com/sdks/php), [shell](https://docs.rarebl.com/sdks/shell).

```bash JavaScript
curl -fsSLO https://docs.rarebl.com/sdk/js/rarebl.mjs
curl -s https://docs.rarebl.com/sdk/SHA256SUMS | grep " js/rarebl.mjs"; sha256sum rarebl.mjs
```

```bash Python
curl -fsSLO https://docs.rarebl.com/sdk/python/rarebl.py
curl -s https://docs.rarebl.com/sdk/SHA256SUMS | grep " python/rarebl.py"; sha256sum rarebl.py
```

```bash PHP
curl -fsSLO https://docs.rarebl.com/sdk/php/Rarebl.php
curl -s https://docs.rarebl.com/sdk/SHA256SUMS | grep " php/Rarebl.php"; sha256sum Rarebl.php
```

```bash Shell
curl -fsSLO https://docs.rarebl.com/sdk/shell/rarebl && chmod +x rarebl
curl -s https://docs.rarebl.com/sdk/SHA256SUMS | grep " shell/rarebl"; sha256sum rarebl
```

**You should see** the two hashes match. Put the file next to your script.

## Step 2 — Create or load a key

Generate a key locally, or load one you already have. Keys never leave this process.

```js JavaScript
import { Rarebl, keys } from './rarebl.mjs';

const me = keys.generate('btc', 'p2wpkh');                         // or keys.fromPrivate('btc', process.env.BTC_WIF, 'p2wpkh')
console.log(me.address);                                           // fund this address, keep me.privateKey secret
const rarebl = new Rarebl();                                       // https://api.rarebl.com
```

```python Python
import os, rarebl

me = rarebl.keys.generate("btc", "p2wpkh")                         # or rarebl.keys.fromPrivate("btc", key)
print(me["address"])                                               # fund this address, keep me["privateKey"] secret
c = rarebl.Rarebl()                                                # https://api.rarebl.com
```

```php PHP
<?php
require 'Rarebl.php';

$me = Rarebl\Keys::generate('btc', 'p2wpkh');                      // or Rarebl\Keys::fromPrivate('btc', $key)
echo $me['address'], "\n";                                         // fund this address, keep $me['privateKey'] secret
$c = new Rarebl\Rarebl();                                          // https://api.rarebl.com
```

```bash Shell
rarebl keygen --chain btc --type p2wpkh > btc.json                 # prints the new address and key: keep this file private
jq -r .privateKey btc.json > btc.key; chmod 600 btc.key
jq -r .address btc.json
```

**You should see** a new address. Send it a small amount and wait for a confirmation before you continue. Keep keys out of source control and out of command lines.

## Step 3 — Send BTC

On BTC, LTC and BCH the sender is watched first so the API can list its UTXOs. The JavaScript and shell SDKs let you start that explicitly; Python and PHP do it automatically the first time. See [Watch addresses](https://docs.rarebl.com/guides/watch-addresses).

```js JavaScript
await rarebl.watch('btc', me.address);                             // waits until the watch is active

const txid = await rarebl.transfer({
  chain: 'btc', from: me.address, to: 'bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm',
  amount: '0.0015', key: me.privateKey, priority: 'standard',      // or feeRate: 12 (sat/vB)
});
console.log(txid);
```

```python Python
txid = c.transfer(chain="btc", from_=me["address"], to="bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm",
                  amount="0.0015", key=me["privateKey"], priority="standard")   # or fee_rate=12 (sat/vB)
print(txid)
```

```php PHP
$txid = $c->transfer([
    'chain' => 'btc', 'from' => $me['address'], 'to' => 'bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm',
    'amount' => '0.0015', 'key' => $me['privateKey'], 'priority' => 'standard',
]);
echo $txid, "\n";
```

```bash Shell
rarebl watch --chain btc "$(jq -r .address btc.json)"
rarebl transfer --chain btc --from "$(jq -r .address btc.json)" --to bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm \
  --amount 0.0015 --key-file btc.key --priority standard           # prints the txid
```

**You should see** the transaction id (a 64-character hex string). Behind that one call, the SDK built the transaction, recomputed every digest, checked that it pays exactly what you asked (recipient, amount, change back to you, a fee cap), signed, assembled and broadcast. If anything differs it raises `VerifyError` before signing.

## Step 4 — Send ETH or a token on Ethereum

Ethereum needs a nonce and gas. The API supplies the nonce and fee suggestions; you can pin them with `maxFee` (a cap in wei). For an ERC-20 token, `token` is the contract address and `amount` is in whole token units.

```js JavaScript
const txid = await rarebl.transfer({
  chain: 'eth', from: '0xYourAddress', to: '0xRecipient', amount: '25',
  token: '0xdac17f958d2ee523a2206206994597c13d831ec7',             // USDT; leave out `token` to send ETH
  key: process.env.ETH_KEY,
});
```

```python Python
txid = c.transfer(chain="eth", from_="0xYourAddress", to="0xRecipient", amount="25",
                  token="0xdac17f958d2ee523a2206206994597c13d831ec7", key=os.environ["ETH_KEY"],
                  max_fee=21000 * 40 * 10**9)                      # cap in wei
```

```php PHP
$txid = $c->transfer([
    'chain' => 'eth', 'from' => '0xYourAddress', 'to' => '0xRecipient', 'amount' => '25',
    'token' => '0xdac17f958d2ee523a2206206994597c13d831ec7', 'key' => getenv('ETH_KEY'),
]);
```

```bash Shell
rarebl transfer --chain eth --from 0xYourAddress --to 0xRecipient --amount 25 \
  --token 0xdac17f958d2ee523a2206206994597c13d831ec7 --key-env ETH_KEY
```

**You should see** the transaction hash. The sender needs ETH for gas; a deposit address that holds only USDT cannot send until it has some.

## Step 5 — Send USDT on TRON

`token` is the TRC-20 contract. A TRON transfer uses energy and bandwidth; what the account lacks is paid by burning TRX, capped by `feeLimit` (in sun, 1 TRX = 1,000,000 sun). Check what the account has with [Address resources](https://docs.rarebl.com/api/address/resources).

```js JavaScript
const txid = await rarebl.transfer({
  chain: 'tron', from: 'TYourAddress', to: 'TRecipient', amount: '25',
  token: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',                     // USDT-TRC20
  key: process.env.TRON_KEY,                                       // 64 hex characters
  feeLimit: 15_000_000,
});
```

```python Python
txid = c.transfer(chain="tron", from_="TYourAddress", to="TRecipient", amount="25",
                  token="TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", key=os.environ["TRON_KEY"],
                  max_fee=100_000_000)                             # feeLimit cap in sun
```

```php PHP
$txid = $c->transfer([
    'chain' => 'tron', 'from' => 'TYourAddress', 'to' => 'TRecipient', 'amount' => '25',
    'token' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', 'key' => getenv('TRON_KEY'),
    'maxFee' => 100000000,                                         // feeLimit cap in sun
]);
```

```bash Shell
rarebl transfer --chain tron --from TYourAddress --to TRecipient --amount 25 \
  --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t --key-env TRON_KEY --max-fee 100000000
```

**You should see** the transaction id. TRON transactions expire (see `expiresAt` in the build reply), so sign and broadcast promptly; the SDK does both in one call.

## Step 6 — Check the result

```bash cURL
curl "https://api.rarebl.com/open/tx/status?chain=btc&id=<txid>"
```

```python Python
print(c.status("btc", txid))
```

**You should see** `status: "pending"` with 0 confirmations, then `"success"`. For a push instead of polling use a `tx.confirmations` [webhook](https://docs.rarebl.com/guides/webhooks).

## Good to know

| Topic | What to do |
| --- | --- |
| Token decimals | USDT and USDC are built in. For any other token pass `decimals` explicitly: the SDK never takes decimals from the server. |
| Fee caps | `max_fee` / `maxFee` caps the fee in base units (sats, wei or sun). The SDK refuses a build that exceeds it. Without one, SDK 0.2.0 applies defaults: 1000 sat/vB on BTC and LTC, 50 sat/byte on BCH and DASH, ETH `maxFeePerGas` 500 gwei and 0.05 ETH in total, TRON `feeLimit` 150 TRX. |
| Pinned recipient | `transfer()` always checks the build against the recipient, amount and token you passed. Signing a build yourself (`signBuild`, `sign_build`, `Signer::signBuild`, `rarebl sign`) needs an `expect` with the recipient too: [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction). |
| Legacy inputs | On BTC, LTC and DASH p2pkh inputs the SDK reads the input amount from the `prevTx` that `tx/build` delivers, after checking that it hashes to the input's txid. |
| Reproducible signatures | ECDSA is always deterministic. Schnorr (p2tr) adds random auxiliary data; pass `deterministic` (`--deterministic` in the shell) for byte-identical output. |
| Not broadcasting yet | Pass `broadcast=False` (`--no-broadcast` in the shell) to get the signed transaction, inspect it with [Decode](https://docs.rarebl.com/api/tx/decode), then [Broadcast](https://docs.rarebl.com/api/tx/broadcast). |
| Token contracts | USDT on `eth`: `0xdac17f958d2ee523a2206206994597c13d831ec7`. USDT on `tron`: `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`. Map others with [Assets](https://docs.rarebl.com/api/market/assets). |

## Common errors

The SDKs raise typed errors that carry `code`, `reason` and `detail`.

| Error | What it means | What to do |
| --- | --- | --- |
| `VerifyError` | The API's reply did not match what you asked for, a digest could not be recomputed, the fee is above the cap, or a legacy p2pkh input lacks its `prevTx`. Raised before any signature. | Do not sign. Retry, and report it with the request id (`meta.requestid` or `X-Request-Id`). |
| `InputError` | Signing a build yourself without `expect` (or without `expect.to`). `transfer()` does not raise it. | Pass the recipient and amount in `expect`, as in [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction). |
| `API409` `not_watched` | BTC, LTC or BCH sender not active yet. | Wait for the watch, then retry. |
| `API422` `insufficient_funds` | Balance cannot cover the amount plus the fee (or gas). | Fund the address, or lower the amount. |
| `API422` `nonce_too_low`, `tx_expired` | ETH nonce behind, or a TRON transaction expired. | Run `transfer()` again. |
| `API422` `node_rejected` | The node refused it; read `detail`. | Often a fee below the relay minimum: raise `priority` or `feeRate`. |
| `API429` | Write limit: 6 per minute, burst 3. | Wait `Retry-After`; queue your payouts. |

More: [Responses & codes](https://docs.rarebl.com/responses-and-codes).

## Next steps

- See what `transfer()` does under the hood, or sign with an HSM: [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).
- Sweep many deposits: [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses).
- Follow confirmations: [Webhooks](https://docs.rarebl.com/guides/webhooks).
- Fix a payment that does not confirm: [Stuck transactions](https://docs.rarebl.com/guides/stuck-transactions).

---

# Stuck transactions: RBF and CPFP

A UTXO transaction can sit unconfirmed because its fee rate is too low for the current mempool. There are two fixes: **replace it** with a higher-fee version (RBF), or **pull it through** with a child that pays a high fee (CPFP). RBF works on Bitcoin and Litecoin; CPFP works on every UTXO chain.

## Before you start

- The txid and chain of the stuck transaction, and the key that signed it.
- To use RBF the original must have signalled replaceability. `rbf` defaults to **true** in [Build](https://docs.rarebl.com/api/tx/build), so transactions you built signal it.
- Ethereum and TRON: v2 builds ETH transactions with the pending nonce and has no call to replace a pending transaction with the same nonce. Wait, or send again once it is confirmed or dropped.

## Step 1 — Find out what is going on

```bash cURL
curl "https://api.rarebl.com/open/tx/status?chain=btc&id=<txid>"
curl "https://api.rarebl.com/open/tx/outspends?chain=btc&id=<txid>"
curl "https://api.rarebl.com/open/fees/recommended?chain=btc"
```

```python Python
print(c.status("btc", txid))
print(c.outspends("btc", txid))
```

```bash Shell
rarebl status --chain btc <txid>
```

**You should see** `status: "pending"` with 0 confirmations. Then compare:

- The transaction's fee rate (`feeRate` in [Transaction](https://docs.rarebl.com/api/tx/get)) against the `fast` and `standard` rates from [Recommended fees](https://docs.rarebl.com/api/fees/recommended).
- [Output spend status](https://docs.rarebl.com/api/tx/outspends): whether its outputs are spent in the mempool, which matters for CPFP.
- A `tx.dropped` [webhook](https://docs.rarebl.com/guides/webhooks) fires when a transaction has been gone for 24 hours, and `tx.replaced` fires when it is replaced (with the new txid).

## Step 2 — Choose a fix

| Fix | Use when | Chains |
| --- | --- | --- |
| **RBF**: rebuild with the same inputs and a higher `feeRate` | You built the transaction and it signalled `rbf`. | BTC, LTC |
| **CPFP**: spend an unconfirmed output of the stuck transaction with a high fee | You own an output of it (usually your change), or RBF is not possible. | All UTXO chains |

## Step 3 — Replace it (RBF)

Build again with the **same inputs** and recipient and a **higher `feeRate`** (above the original, with room for the network's replacement rules). Spending a different set of inputs creates a second payment instead of a replacement.

```bash cURL
curl -X POST https://api.rarebl.com/open/tx/build -H "Content-Type: application/json" -d '{
  "chain": "btc",
  "inputs": [{"txid": "<same input txid>", "vout": 1}],
  "to": [{"address": "<same recipient>", "amount": "0.0015"}],
  "change": "<your change address>",
  "feeRate": "40",
  "rbf": true
}'
```

```python Python
build = c.build({"chain": "btc", "inputs": [{"txid": input_txid, "vout": 1}],
                 "to": [{"address": dest, "amount": "0.0015"}], "change": addr, "feeRate": "40", "rbf": True})
sigs = rarebl.sign_build(build, key, expect={"to": {"address": dest, "amount": "0.0015"}})   # verifies every digest first
c.assemble(build["unsigned"], sigs, broadcast=True)
```

`expect` is required when you sign, so name the same recipient and amount as the original payment; change may only return to your own input addresses. The default fee cap is 1000 sat/vB (BTC, LTC), so a replacement above that needs `maxFeeRate` in `expect`.

**You should see** a new `unsigned` and `toSign` with a higher `feeRate`. Verify, sign, assemble and broadcast as in [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction); the new transaction replaces the old one in the mempool. A `tx.replaced` webhook, or [Transaction status](https://docs.rarebl.com/api/tx/status), tells you which txid won.

## Step 4 — Or pull it through (CPFP)

Spend an **unconfirmed output of the stuck transaction** in a new transaction with a high fee, so miners include both together. The change output of your own payment is the usual candidate.

1. Find the output (for example `n: 1`, your change) in [Transaction](https://docs.rarebl.com/api/tx/get) and confirm it is unspent with [Output spend status](https://docs.rarebl.com/api/tx/outspends).
2. Build with **exact `inputs`** pointing at that output and a higher `feeRate`, sending to an address you control:

```json
{
  "chain": "btc",
  "inputs": [{"txid": "<stuck txid>", "vout": 1}],
  "to": [{"address": "bc1q…your own address", "amount": "max"}],
  "feeRate": "60"
}
```

**You should see** a build with one input and no change. Sign it with `expect` set to your own address and `amount: "max"` (a `max` spend must leave no change output), then broadcast it. If the node does not accept the unconfirmed input, the build fails with `inputs_unknown` or `inputs_spent`.

## Step 5 — Choose the rate

The miner looks at the parent and the child **together**. To reach a target rate, the child's fee must cover its own size and the parent's shortfall: `child fee = target × (parent vsize + child vsize) − parent fee`. For example, a 141 vB parent that paid 705 sats (5 sat/vB) and a 110 vB child, aiming for 40 sat/vB overall, needs a child fee of `40 × 251 − 705 = 9,335` sats, about 85 sat/vB on the child. [Estimate](https://docs.rarebl.com/api/tx/estimate) gives you the child's size before you commit.

## Prevention

- Use `priority: "fast"` or a fixed `feeRate` from [Recommended fees](https://docs.rarebl.com/api/fees/recommended) for payouts that matter.
- Keep `rbf: true` (the default) on Bitcoin and Litecoin.
- Follow every payment with a `tx.confirmations` [webhook](https://docs.rarebl.com/guides/webhooks) so you notice stuck ones quickly.

## Common errors

| Reason | What it means | What to do |
| --- | --- | --- |
| `API422` `inputs_spent` | The input was already spent, maybe by the replacement or by the transaction itself. | Check [Output spend status](https://docs.rarebl.com/api/tx/outspends) and the new txid. |
| `API422` `inputs_unknown` | The node does not know that unconfirmed input. | Wait for the parent to propagate, or rebuild. |
| `API422` `node_rejected` | The node refused the replacement, for example `insufficient fee` or `min relay fee not met`. | Raise `feeRate`: a replacement must pay more than the original. |
| `API422` `fee_too_high` | The fee is above the safety limit. | Lower `feeRate`. |
| `API429` | Compute: 2 per second; write: 6 per minute. | Wait `Retry-After`. |

## Next steps

- [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction): the verify, sign and broadcast steps.
- [Webhooks](https://docs.rarebl.com/guides/webhooks): `tx.confirmations`, `tx.dropped`, `tx.replaced`.
- [Errors and rate limits](https://docs.rarebl.com/guides/handle-errors).

---

# Hosted signing

Hosted signing lets Rarebl sign for you: you send a private key with the request, and the signer builds, signs or generates keys in memory and forgets the key. It is a good fit for a quick script or an environment that cannot run an SDK. The key reaches Rarebl over TLS, wrapped in an encrypted envelope that is bound to one chain, one operation and what may be signed; signing locally with an SDK keeps keys on your side ([Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally)).

The three endpoints:

| Endpoint | What it does |
| --- | --- |
| [tx/sign](https://docs.rarebl.com/api/tx/sign) | Signs an `unsigned` transaction from `tx/build`. Never broadcasts. |
| [tx/send](https://docs.rarebl.com/api/tx/send) | Builds, signs and broadcasts in one call. |
| [address/new](https://docs.rarebl.com/api/address/new) | Generates a new keypair in the signer and returns it once. |

Every hosted request needs the header `X-Rarebl-Accept-Risk: hosted-signing`. Without it the API answers `API403` with reason `risk_not_acknowledged`.

## Before you start

- A key to sign with, as a WIF or 64-character hex string, for an address that holds funds.
- SDK 0.2.0 or later ([JavaScript](https://docs.rarebl.com/sdks/js), [Python](https://docs.rarebl.com/sdks/python) or [PHP](https://docs.rarebl.com/sdks/php)), which builds the envelope, or your own X25519 and AES-GCM code (format at the end of step 3). Envelope v1, which earlier SDK versions produced, is refused with `bad_envelope`.
- Try It is disabled for these endpoints on this site, so that a private key is never typed into a web page. Use your own server.

## Step 1 — Fetch the signer key

The signer publishes a public X25519 key. Encrypt your private key to it so that only the signer process can read it; the web server, the firewall and PHP only see ciphertext.

```bash cURL
curl https://api.rarebl.com/open/tx/signer-key
```

```js JavaScript
import { Rarebl, envelope } from './rarebl.mjs';

const rarebl = new Rarebl();
const signer = await rarebl.signerKey();           // {kid, alg, publicKey, expiresAt}: pass it whole to envelope.encrypt
```

```python Python
import os, rarebl

c = rarebl.Rarebl()
signer = c.signer_key()                            # {kid, alg, publicKey, expiresAt}: pass it whole to envelope.encrypt
```

```php PHP
<?php
require 'Rarebl.php';
use Rarebl\{Rarebl, Envelope};

$c = new Rarebl();
$signer = $c->signerKey();                         // ['kid' => ..., 'publicKey' => ..., 'expiresAt' => ...]
```

**You should see** a key id, the algorithm and the public key. Keys rotate: the previous `kid` stays valid for 7 days after its successor was created, and a key is refused 7 days after its `expiresAt`. Fetch the key when you need it instead of hard-coding it.

```json
{ "status": 1, "code": "API200", "message": "success",
  "data": { "kid": "k20261115-defd9c", "alg": "X25519", "publicKey": "wL-KbhcrI3WWpG1nv8sNAoiWUVTyw9yMxfn1_jvoxT4", "expiresAt": "2026-12-15T00:12:34.514Z" },
  "go": null, "meta": { "requestid": "0123456789abcdef", "notices": [] } }
```

## Step 2 — Build the transaction (tx/sign only)

For [tx/sign](https://docs.rarebl.com/api/tx/sign) you sign a transaction you built with [tx/build](https://docs.rarebl.com/api/tx/build), and the envelope names the digests of that build. Build it, then check the reply as in [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction) before you let anyone sign it. With [tx/send](https://docs.rarebl.com/api/tx/send) there is nothing to build first: skip to step 3 and name the recipients instead.

```js JavaScript
import { describeBuild } from './rarebl.mjs';

const to = 'bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm';
const reply = await rarebl.build({ chain: 'btc', from: [from], to: [{ address: to, amount: '0.0015' }], priority: 'standard' });
console.log(describeBuild(reply, { expect: { to: [{ address: to, amount: '0.0015' }] } }));   // throws VerifyError on a mismatch
```

```python Python
to = "bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm"
reply = c.build({"chain": "btc", "from": [from_addr], "to": [{"address": to, "amount": "0.0015"}], "priority": "standard"})
rarebl.verify_build(reply, expect={"to": {"address": to, "amount": "0.0015"}})        # raises VerifyError on a mismatch
```

```php PHP
$to = 'bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm';
$reply = $c->build(['chain' => 'btc', 'from' => [$from], 'to' => [['address' => $to, 'amount' => '0.0015']], 'priority' => 'standard']);
Rarebl\Signer::verifyBuild($reply, null, ['to' => ['address' => $to, 'amount' => '0.0015']]);   // throws VerifyException on a mismatch
```

**You should see** no error, and `reply.toSign` with one digest per input.

## Step 3 — Encrypt the key into an envelope

The envelope carries your private key together with the rules the signer enforces. It is bound to:

- **the chain** (`chain`), which must be the chain of the request;
- **the operation** (`op`): `sign` for `tx/sign`, `send` for `tx/send`;
- **what may be signed**: for `sign`, the exact list of `toSign` digests (`digests`); for `send`, the recipients and amounts (`bind.to`, as base-unit integers, plus `bind.token` for a token transfer);
- **a lifetime**: it expires within 300 seconds (`exp`) and opens once (`jti`).

The SDKs fill in `exp` and `jti`. For `tx/sign`, name the digests of the build you checked:

```js JavaScript
const digests = reply.toSign.map((t) => t.digest);                           // the digests you just verified
const encrypted = await envelope.encrypt(signer, {
  privateKeys: [process.env.BTC_WIF], op: 'sign', chain: 'btc', digests,
});
```

```python Python
digests = [t["digest"] for t in reply["toSign"]]                              # the digests you just verified
encrypted = rarebl.envelope.encrypt(signer, {
    "privateKeys": [os.environ["BTC_WIF"]], "op": "sign", "chain": "btc", "digests": digests,
})                                                                            # needs the `cryptography` package for AES-GCM
```

```php PHP
$digests = array_column($reply['toSign'], 'digest');                          // the digests you just verified
$encrypted = Envelope::encrypt($signer, [
    'privateKeys' => [getenv('BTC_WIF')], 'op' => 'sign', 'chain' => 'btc', 'digests' => $digests,
]);
```

For `tx/send`, name the recipients. `bindOf` converts whole-unit amounts to base units (satoshi, wei, sun or token units):

```js JavaScript
const bind = envelope.bindOf('btc', [{ address: to, amount: '0.0015' }]);     // token transfers: { token: '0x…' } as the third argument
const encrypted = await envelope.encrypt(signer, {
  privateKeys: [process.env.BTC_WIF], op: 'send', chain: 'btc', bind,
});
```

```python Python
bind = rarebl.envelope.bind_of("btc", {"address": to, "amount": "0.0015"})          # token transfers: token="0x…"
encrypted = rarebl.envelope.encrypt(signer, {
    "privateKeys": [os.environ["BTC_WIF"]], "op": "send", "chain": "btc", "bind": bind,
})
```

```php PHP
$bind = Envelope::bindOf('btc', ['address' => $to, 'amount' => '0.0015']);          // token transfers: the contract as the third argument
$encrypted = Envelope::encrypt($signer, [
    'privateKeys' => [getenv('BTC_WIF')], 'op' => 'send', 'chain' => 'btc', 'bind' => $bind,
]);
```

**You should see** a long base64url string. Send it as `keys.encrypted`.

If you build the envelope yourself, it is `base64url(JSON {v:2, kid, epk, iv, ct, tag})` with every field base64url without padding. Generate a fresh ephemeral X25519 key `epk`, derive the shared secret with the signer's public key, then HKDF-SHA256 with an empty salt and the info `"rarebl-signer-v2" || epk || recipientPub` (the ASCII label, your 32-byte `epk`, the signer's 32-byte public key, all raw) to get a 32-byte key. Encrypt with AES-256-GCM, a 12-byte IV and the AAD `info || utf8(kid)`; `ct` is the ciphertext and `tag` the 16-byte tag. The plaintext is JSON:

```json
{ "v": 2, "privateKeys": ["<key>"], "exp": 1794000000, "jti": "<32 lowercase hex>", "op": "sign", "chain": "btc", "digests": ["<hex>"] }
```

`exp` is in unix seconds and must be at most 300 seconds ahead. For `op: "send"` replace `digests` with `"bind": {"to": [{"address": "…", "amount": "150000"}]}` (at most 10 recipients; `"max"` is accepted on UTXO chains) and add `"token": "<contract>"` inside `bind` for a token transfer.

A plain `{"privateKeys": [...]}` body is still accepted, but it carries no binding: nothing limits what the key signs, and anything on the path can read it. Prefer the envelope.

## Step 4 — Sign, or build, sign and send

Use [tx/sign](https://docs.rarebl.com/api/tx/sign) with the `unsigned` transaction from step 2, then broadcast the result yourself. Or use [tx/send](https://docs.rarebl.com/api/tx/send) for one call that builds, signs and broadcasts: the body is a `tx/build` body plus `keys`.

```bash cURL
curl -X POST https://api.rarebl.com/open/tx/send \
  -H "Content-Type: application/json" \
  -H "X-Rarebl-Accept-Risk: hosted-signing" \
  -d '{
    "chain": "btc",
    "from": ["bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q"],
    "to": [{"address": "bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm", "amount": "0.0015"}],
    "priority": "standard",
    "keys": { "encrypted": "BASE64URL_ENVELOPE" }
  }'
```

```js JavaScript
const hdr = { 'X-Rarebl-Accept-Risk': 'hosted-signing' };

// tx/send: the envelope was made with op 'send'
const sent = await rarebl.request('POST', '/open/tx/send', {
  chain: 'btc', from: [from], to: [{ address: to, amount: '0.0015' }], priority: 'standard',
  keys: { encrypted },
}, hdr);

// tx/sign: the envelope was made with op 'sign'
const signedOnly = await rarebl.request('POST', '/open/tx/sign', { unsigned: reply.unsigned, keys: { encrypted } }, hdr);
```

```python Python
hdr = {"X-Rarebl-Accept-Risk": "hosted-signing"}

# tx/send: the envelope was made with op "send"
sent = c.post("/open/tx/send", {
    "chain": "btc", "from": [from_addr], "to": [{"address": to, "amount": "0.0015"}], "priority": "standard",
    "keys": {"encrypted": encrypted},
}, headers=hdr)

# tx/sign: the envelope was made with op "sign"
signed_only = c.post("/open/tx/sign", {"unsigned": reply["unsigned"], "keys": {"encrypted": encrypted}}, headers=hdr)
```

```php PHP
$hdr = ['X-Rarebl-Accept-Risk' => 'hosted-signing'];

// tx/send: the envelope was made with op 'send'
$sent = $c->post('/open/tx/send', [
    'chain' => 'btc', 'from' => [$from], 'to' => [['address' => $to, 'amount' => '0.0015']], 'priority' => 'standard',
    'keys' => ['encrypted' => $encrypted],
], $hdr);

// tx/sign: the envelope was made with op 'sign'
$signedOnly = $c->post('/open/tx/sign', ['unsigned' => $reply['unsigned'], 'keys' => ['encrypted' => $encrypted]], $hdr);
```

**You should see** `signed` and, for `tx/send`, the `broadcast` result. `tx/sign` returns only `signed`: broadcast it with [Broadcast](https://docs.rarebl.com/api/tx/broadcast).

```json
{ "signed": { "chain": "btc", "hex": "…", "txid": "…" }, "broadcast": { "txid": "…", "accepted": true, "alreadyKnown": false } }
```

An envelope opens once. If a request fails after the signer read it (a refusal or a timeout), make a new envelope for the retry: resending the same one answers `envelope_replayed`.

## Step 5 — Generate a key (optional)

[address/new](https://docs.rarebl.com/api/address/new) generates a keypair in the signer and returns it once. Pass `encryptTo` (your own X25519 public key, base64url) to get the private key back as an envelope encrypted to you (`encryptedPrivateKey`); open it with `envelope.decrypt` (`Envelope::decrypt` in PHP). Generating keys locally with the SDK (`keys.generate`) avoids the round trip.

## How it is protected

These rules are enforced by the API:

| Rule | What it means |
| --- | --- |
| Risk header | `X-Rarebl-Accept-Risk: hosted-signing` on every request, otherwise `API403` `risk_not_acknowledged`. |
| Scoped envelope | An envelope is bound to its chain and operation, expires within 300 seconds and opens once. `sign` signs only the digests it names; `send` pays only the recipients and amounts it names, and any other output must return to an input address. |
| Body only | Keys are accepted in a `POST` body only. A key-like value in the query string gives `API400` `plaintext_key_in_query` and the request is dropped unprocessed. |
| Key matching | Every key must derive the address of an input it signs (`key_mismatch`); unused keys are refused. |
| No retention | A separate signer process (unix socket, no network) uses the key in memory and wipes it. Keys are never written to disk, logs, the database, caches or error reports, and request bodies on these paths are excluded from all logging. |
| Key rotation | The signer key rotates; a retired key is refused 7 days after its `expiresAt`. |
| Limits | The write rate class (6 per minute, burst 3, 300 per day) and at most 10 inputs per request. |
| Replies | Always `Cache-Control: no-store`. |

Only the txid, chain, time and a hashed IP of a broadcast are recorded.

## Common errors

| Reply | What it means | What to do |
| --- | --- | --- |
| `API403` `risk_not_acknowledged` | The header is missing. | Add `X-Rarebl-Accept-Risk: hosted-signing`. |
| `API403` `key_mismatch` | A key does not derive the address of an input it signs. | Send only the keys of the input addresses. |
| `API403` `digest_not_bound` | `tx/sign`: the digests of the `unsigned` transaction are not exactly the ones in the envelope. Nothing was signed. | List every `toSign` digest of this build, and only those, in `digests`. |
| `API403` `outputs_not_bound` | `tx/send`: the transaction does not pay exactly the recipients and amounts in `bind` (or has an output that does not return to an input address). Nothing was signed. | Make `bind` match the `to` of the request, in base units; use `envelope.bindOf`. |
| `API400` `bad_envelope` | The envelope is unreadable, is a v1 envelope, names an unknown `kid`, has an `op` that does not match the route, or an `exp` more than 300 seconds ahead. | Fetch the signer key again and encrypt again with SDK 0.2.0 or later. |
| `API400` `envelope_expired` | The envelope's `exp` has passed. | Make a new envelope right before the request. |
| `API409` `envelope_replayed` | The envelope was already used. | Make a new envelope for every request. |
| `API400` `chain_mismatch` | The envelope's `chain` is not the chain of the request. | Use the same chain in the envelope and the request. |
| `API400` `plaintext_key_in_query` | A key-like value was in the URL. | Move it into the POST body (as an envelope). |
| `API400` with `param: "keys"` | A `keys` member is malformed. | Send `{"encrypted": "…"}` or `{"privateKeys": [...]}`. |
| `API422` `tx_too_large` | More than 10 inputs. | Split the spend. |
| `API502` `signer_unavailable` | The signer is not reachable. | Retry with back-off, with a new envelope. |
| `API429` | Write rate limit. | Wait `Retry-After` seconds. |

When a request answers `bad_envelope` or an unknown `kid`, fetch [Signer key](https://docs.rarebl.com/api/tx/signer-key) again before you retry: the key may have rotated. Build and broadcast errors (`insufficient_funds`, `node_rejected` and others) are the same as in [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).

## Next steps

- The local alternative: [Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally) and [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).
- Endpoint details: [tx/sign](https://docs.rarebl.com/api/tx/sign), [tx/send](https://docs.rarebl.com/api/tx/send), [address/new](https://docs.rarebl.com/api/address/new), [Signer key](https://docs.rarebl.com/api/tx/signer-key).

---

# Errors and rate limits

Production code needs to know which failures to retry, which to fix and how fast it may call. You will read the error envelope, retry the right things with back-off, make writes safe to repeat and stay under the per-IP rate limits. The reference tables are in [Responses & codes](https://docs.rarebl.com/responses-and-codes) and [Rate limits](https://docs.rarebl.com/rate-limits).

## Before you start

- Every reply, success or error, has the same envelope `{status, code, message, data, go, meta}` and the HTTP status matches the code.
- Branch on `code` and `data.reason`, never on `message`: messages can change.
- Every reply carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-Request-Id`. Log the request id (`meta.requestid`, the same value): support will ask for it.

## Step 1 — Read the error

An error has `status: 0`, an `API*` code and often a `data` object with the detail.

```json
{ "status": 0, "code": "API422", "message": "The node rejected the transaction.", "data": { "reason": "node_rejected", "detail": "min relay fee not met" }, "go": null, "meta": { "requestid": "0123456789abcdef", "notices": [] } }
```

```js JavaScript
const res = await fetch(url, options);
const body = await res.json();
if (body.code !== 'API200') {
  const { reason, param, detail } = body.data ?? {};
  console.warn(body.code, reason ?? param, detail, body.meta?.requestid);
}
```

```python Python
try:
    c.broadcast("btc", hex_tx)
except rarebl.ApiError as e:
    print(e.code, e.reason, e.detail)            # for example API422 node_rejected "min relay fee not met"
```

```php PHP
try {
    $c->broadcast('btc', $hex);
} catch (Rarebl\ApiException $e) {
    error_log($e->apiCode . ' ' . $e->reason . ' ' . $e->detail);
}
```

**You should see** the code, the reason and the node's detail. The SDKs raise typed errors (`ValidationError`, `ConflictError`, `UnprocessableError`, `RateLimitError` and others) that carry the same fields.

## Step 2 — Decide: retry, wait or fix

| Code | Meaning | What to do |
| --- | --- | --- |
| `API429` | Rate limited. | **Wait** `Retry-After` seconds, then retry. |
| `API502` | A node is unavailable, syncing or timed out. | **Retry** with back-off. |
| `API500` | Internal error. | Retry once or twice; report it with the request id. |
| `API409` | Not available yet on this chain, or a precondition is missing (`data.reason` says which). | Not a failure of your request. Start the watch on `not_watched`; otherwise try later. |
| `API422` | Well-formed, but the node or our checks reject it. | **Change the transaction** (fund it, raise the fee, rebuild). Do not retry it unchanged. |
| `API400`, `API403`, `API404`, `API405` | A bad parameter, a policy refusal, a missing object or a wrong method. | **Fix the request.** Do not retry unchanged. |

## Step 3 — Retry with back-off

Retry only what can succeed later: `API429` and `API502` (and `API500` briefly). Honour `Retry-After`, double the delay up to a ceiling and add jitter.

```js JavaScript
async function call(url, options, tries = 4) {
  let delay = 1000;
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url, options);
    const body = await res.json();
    if (body.code === 'API200') return body.data;
    if (body.code === 'API429') delay = Number(res.headers.get('Retry-After') ?? 1) * 1000;
    else if (body.code !== 'API502' && body.code !== 'API500') throw Object.assign(new Error(body.message), { code: body.code, data: body.data });
    await new Promise((r) => setTimeout(r, delay + Math.random() * 250));
    delay = Math.min(delay * 2, 30000);
  }
  throw new Error('gave up');
}
```

```python Python
import random, time

def call(fn, tries=4):
    delay = 1.0
    for _ in range(tries):
        try:
            return fn()
        except rarebl.ApiError as e:
            if e.code not in ("API429", "API502", "API500"):
                raise                                   # fix the request or the transaction
            time.sleep(delay + random.random() * 0.25)
            delay = min(delay * 2, 30)
    raise RuntimeError("gave up")
```

**You should see** transient failures absorbed and permanent ones surfaced at once.

## Step 4 — Make writes safe to repeat

A retried broadcast must never pay twice. Send an `Idempotency-Key` on [Broadcast](https://docs.rarebl.com/api/tx/broadcast): the same key, or the same txid, within 24 hours returns the first result. Use one stable key per payout (for example your payout id), and queue payouts instead of firing them in a burst: the write class allows 6 per minute (burst 3) and 300 per day.

```bash cURL
curl -X POST https://api.rarebl.com/open/tx/broadcast -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-7781" -d '{"chain":"btc","hex":"0200000001…"}'
```

**You should see** `alreadyKnown: true` (or the same txid) if you send it again.

## Step 5 — Stay under the rate limits

Limits are per IP address, by rate class; each class is its own bucket, so a burst of builds does not use up your reads.

| Class | Endpoints | Limit |
| --- | --- | --- |
| read | v1 reads, UTXOs, nonce, resources, outspends, market, `hooks/get`, `hooks/deliveries` | 5 per second, burst 20 |
| compute | decode, estimate, build, assemble (without broadcast), address validate | 2 per second, burst 10 |
| write | broadcast, assemble with `broadcast: true`, hosted sign, send and new address | 6 per minute, burst 3; 300 per day |
| watch | address watch | 30 per minute; 2,000 addresses per day |
| hooks | create, update, pause, resume, delete, test, replay | 10 per minute; 100 active subscriptions per IP |
| stream | `wss://api.rarebl.com/ws` | 3 connections; 200 channels per connection |

- Prefer [webhooks](https://docs.rarebl.com/guides/webhooks) or the [WebSocket](https://docs.rarebl.com/guides/websocket) to polling, cache what does not change, and poll no faster than the data changes ([Data freshness](https://docs.rarebl.com/data-freshness)).
- Many users behind one address (an office, a carrier, your own backend) share one bucket. Run heavy work from your own server.

## Common errors

| Reason | What it means | What to do |
| --- | --- | --- |
| `API429` | A bucket is empty. | Wait `Retry-After`; slow down or cache. |
| `API409` `not_watched` | BTC, LTC or BCH address not watched and active. | [Watch it](https://docs.rarebl.com/guides/watch-addresses). |
| `API409` `tx_index_pending`, `history_unavailable`, `before_history_start`, `no_mempool_view` | Data that is not available on this chain right now. | See [Coverage and limits](https://docs.rarebl.com/limits-today). |
| `API422` `insufficient_funds`, `dust_output`, `fee_too_low`, `fee_too_high` | The transaction cannot be built or relayed as asked. | Fund it, change the amount or the fee. |
| `API422` `inputs_spent`, `inputs_unknown` | An input is spent or unknown. | Re-list the UTXOs and build again. |
| `API422` `bad_signature`, `nonce_too_low`, `chain_id_mismatch`, `tx_expired`, `tx_too_large` | A signing or chain-rule problem. | Rebuild and sign again. |
| `API422` `node_rejected` | The node refused it; `data.detail` has its message. | Read `detail`. |
| `API403` `risk_not_acknowledged`, `key_mismatch` | Hosted signing: the header is missing, or a key does not match. | See [Hosted signing](https://docs.rarebl.com/guides/hosted-signing). |
| `API502` | A node is unavailable. | Retry with back-off. |

## Next steps

- [Responses & codes](https://docs.rarebl.com/responses-and-codes) and [Rate limits](https://docs.rarebl.com/rate-limits): the full tables.
- [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction): the errors specific to building and broadcasting.
- [Coverage and limits](https://docs.rarebl.com/limits-today): what is not available on which chain.

---

# Everything a platform needs

This is what a platform like Rarebl needs from a chain API (deposits, sweeps, payouts, settlement, rates) and where the Open API provides it. Every row links to the endpoints and guides involved.

| Need | Where it is in the API |
| --- | --- |
| Create deposit addresses | The SDK generates keys locally and derives addresses (`keys.generate`, recommended): [Sign locally with the SDK](https://docs.rarebl.com/guides/sign-locally). Or [New address (hosted)](https://docs.rarebl.com/api/address/new): [Hosted signing](https://docs.rarebl.com/guides/hosted-signing). |
| Validate an address | [Validate an address](https://docs.rarebl.com/api/address/validate). |
| Detect deposits | [Webhooks](https://docs.rarebl.com/guides/webhooks) of type `address.activity` ([Create a webhook](https://docs.rarebl.com/api/hooks/create)); the WebSocket `address:*` channels ([Live data over WebSocket](https://docs.rarebl.com/guides/websocket)); [Address transactions](https://docs.rarebl.com/api/address/transactions) (DASH now, watched addresses on BTC, LTC and BCH from their watch time, ETH and TRON as the explorer index lands). |
| Verify deposits and confirmations | [Transaction](https://docs.rarebl.com/api/tx/get) and [Transaction status](https://docs.rarebl.com/api/tx/status); `tx.confirmations` webhooks: [Track a deposit until it confirms](https://docs.rarebl.com/guides/track-a-deposit). |
| UTXOs and balances for sweeps and payouts | [Watch addresses](https://docs.rarebl.com/api/address/watch) then [Address UTXOs](https://docs.rarebl.com/api/address/utxos) (BTC, LTC, BCH); DASH natively; ETH and TRON through [Address](https://docs.rarebl.com/api/address/balance) and [Address tokens](https://docs.rarebl.com/api/address/tokens): [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses). |
| Fees | [Recommended fees](https://docs.rarebl.com/api/fees/recommended) and [Estimate](https://docs.rarebl.com/api/tx/estimate): [Market data and fees](https://docs.rarebl.com/guides/market-data). |
| Build, sign and broadcast (sweeps, payouts, gas top-ups, token transfers) | [Build](https://docs.rarebl.com/api/tx/build), [Assemble](https://docs.rarebl.com/api/tx/assemble), [Broadcast](https://docs.rarebl.com/api/tx/broadcast); SDK local signing; hosted [Sign](https://docs.rarebl.com/api/tx/sign) and [Send](https://docs.rarebl.com/api/tx/send): [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction), [Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally) (including ERC-20 and TRC-20 tokens). |
| Nonce and resources | [Address nonce](https://docs.rarebl.com/api/address/nonce) (ETH) and [Address resources](https://docs.rarebl.com/api/address/resources) (TRON). |
| Stuck payments (RBF and CPFP) | [Build](https://docs.rarebl.com/api/tx/build) with `rbf`, or exact `inputs` spending your own change at a higher `feeRate`: [Stuck transactions](https://docs.rarebl.com/guides/stuck-transactions). |
| Spent checks before spending | [Output spend status](https://docs.rarebl.com/api/tx/outspends). |
| Settlement (dropped, reverted, replaced) | [Transaction status](https://docs.rarebl.com/api/tx/status); `tx.dropped` and `tx.replaced` webhooks; failed ETH transactions show `status: "failed"`: [Webhooks](https://docs.rarebl.com/guides/webhooks). |
| Rates | [Prices](https://docs.rarebl.com/api/market/price) and [FX](https://docs.rarebl.com/api/market/fx): [Market data and fees](https://docs.rarebl.com/guides/market-data). |

## Where coverage differs by chain

Address history on BTC, LTC, BCH, ETH and TRON, the Ethereum node (still syncing), TRON history (from 2026-09-08) and the time a watch bootstrap takes vary by chain. See [Coverage and limits](https://docs.rarebl.com/limits-today) for the current state.

## Read the rest

- [Errors and rate limits](https://docs.rarebl.com/guides/handle-errors) and [Rate limits](https://docs.rarebl.com/rate-limits): the per-IP classes (read, compute, write, watch, hooks, stream).
- [Responses & codes](https://docs.rarebl.com/responses-and-codes): every code and reason, including `API422` and `API403`.
- [SDKs](https://docs.rarebl.com/sdks/js): [JavaScript](https://docs.rarebl.com/sdks/js), [Python](https://docs.rarebl.com/sdks/python), [PHP](https://docs.rarebl.com/sdks/php), [shell](https://docs.rarebl.com/sdks/shell).
- [API reference](https://docs.rarebl.com/api): every endpoint with Try It.

---

# JavaScript SDK

The JavaScript SDK is an ES module for **Node 18 or later and browsers**, shipped as a single file, `rarebl.mjs`. It builds, verifies and signs transactions **on your machine**; your private key never leaves the process. Version 0.2.0. It is the reference implementation: the Python and PHP SDKs must produce byte-identical ECDSA signatures (and Schnorr signatures when `deterministic` is set).

Crypto comes from the pinned libraries `@noble/curves`, `@noble/hashes` and `@scure/base`, bundled into the single file, so you do not install anything.

## Download

| File | Size | SHA-256 |
| --- | --- | --- |
| [rarebl-sdk-0.2.0.tgz](https://docs.rarebl.com/sdk/js/rarebl-sdk-0.2.0.tgz) | 103.7 KB | `78c11fb5a1c378f55e240556c472b837ed0fbef35b940c63d167ed846e43f5fa` |
| [rarebl.mjs](https://docs.rarebl.com/sdk/js/rarebl.mjs) | 197.7 KB | `7c5bd8fc5e412ae8596cedab97634915fd94d91bf2fb8b863c1656e36b070aea` |

Requires: Node 18 or later, or a browser (ESM). All checksums are in [SHA256SUMS](https://docs.rarebl.com/sdk/SHA256SUMS). Check the file before you use it:

~~~bash
curl -O https://docs.rarebl.com/sdk/js/rarebl.mjs
sha256sum rarebl.mjs
~~~

## Install

Download the file, check it against the SHA-256 above, and import it:

~~~js
import { Rarebl, keys } from './rarebl.mjs';
~~~

A tarball with the source and tests (`rarebl-sdk-0.2.0.tgz`) is next to it. The npm package `@rarebl/sdk` will follow. In a browser use `<script type="module">`. On Node 18 add `globalThis.crypto ??= (await import('node:crypto')).webcrypto;` first (Node 20 and later have it).

## Ten lines: send BTC

~~~js
import { Rarebl, keys } from './rarebl.mjs';

const me = keys.fromPrivate('btc', process.env.BTC_WIF, 'p2wpkh');   // or keys.generate('btc')
const rarebl = new Rarebl();                                          // https://api.rarebl.com

await rarebl.watch('btc', me.address);                                // BTC, LTC, BCH: start watching, wait until active

const txid = await rarebl.transfer({
  chain: 'btc', from: me.address, to: 'bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm', amount: '0.0015',
  key: process.env.BTC_WIF, priority: 'standard',                     // or feeRate: 12 (sat/vB)
});
console.log(txid);
~~~

## Send USDT on TRON

~~~js
const txid = await rarebl.transfer({
  chain: 'tron', from: 'T...sender', to: 'T...recipient', amount: '25',
  token: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',   // USDT-TRC20; decimals are known to the SDK, other tokens need decimals: n
  key: process.env.TRON_KEY,                       // 64 hex characters
});
~~~

ETH works the same (`chain: 'eth'`, `token: '0xdac17f958d2ee523a2206206994597c13d831ec7'` for USDT). The sender needs TRX or ETH for fees.

## `transfer()`

`transfer` builds the transaction on the API, **recomputes every digest and checks that it pays exactly what you asked** (recipient, amount, change back to you, fee cap), signs on your machine, then assembles and broadcasts. It throws `VerifyError` before signing if anything differs. Amounts are decimal strings in whole units: do not pass numbers for money.

## Lower level: build, describe, sign, assemble

~~~js
import { describeBuild, signBuild } from './rarebl.mjs';

const reply = await rarebl.build({ chain: 'btc', from: [addr], to: [{ address, amount: '0.001' }], priority: 'fast' });
const summary = describeBuild(reply, { expect: { to: [{ address, amount: '0.001' }] } });  // what is really being signed
const signatures = signBuild(reply, [key], { expect: { to: [{ address, amount: '0.001' }] } });  // expect is required; verify is on by default
const { broadcast } = await rarebl.assemble(reply.unsigned, signatures, { broadcast: true });
~~~

| Function | What it does |
| --- | --- |
| `keys.generate`, `keys.fromPrivate` | Local key generation (CSPRNG) and import (hex or WIF). |
| `address.derive`, `address.validate` | Derive and validate addresses. |
| `signDigest` | One signature: DER + sighash byte, BIP340 Schnorr, or recoverable `r‖s‖v`. |
| `verifyBuild` | Recompute every digest and check outputs, amounts, change and fee. |
| `describeBuild` | A readable summary of what a build reply would sign. |
| `signBuild(reply, keys, { expect, unsafeNoExpect?, verify?, deterministic?, prevTxs?, now? })` | Verify, then sign every digest. `expect` is required and must contain `to`; `verify` is on by default. |
| `Rarebl` client | `build`, `assemble`, `broadcast`, `decode`, `estimate`, `status`, `watch`, `utxos`, `nonce`, `resources`, `marketPrice`, `transfer`. |
| `envelope.encrypt(signerKey, { privateKeys, op, chain, digests?, bind?, exp?, jti? })` | Builds an envelope v2 for [hosted signing](https://docs.rarebl.com/guides/hosted-signing); not needed for local signing. `signerKey` is the whole reply of `rarebl.signerKey()`. |
| `envelope.bindOf`, `envelope.seal`, `envelope.decrypt` | `bindOf(chain, to, { token?, decimals? })` converts recipients to the base-unit `bind` of an `op: 'send'` envelope; `decrypt` opens the `encryptedPrivateKey` of an [address/new](https://docs.rarebl.com/api/address/new) reply. |
| `webhook.verify` | Check `X-Rarebl-Signature`. |

`signBuild` refuses to run without `expect` (it must contain `to`): without it nothing pins who is paid. Pass `unsafeNoExpect: true` to sign without pinning the recipients; the default fee caps still apply, and `verify: false` also needs it. `transfer()` always pins what you passed. The `expect` fields are `to`, `change`, `token`, `decimals`, `opReturn`, `from`, `chain` and the fee caps below.

TypeScript types are in the tarball (`src/index.d.ts`).

## Fee caps and defaults

When `expect` gives no cap, the SDK applies one. Override it through `expect`:

| Chain | Default | Override |
| --- | --- | --- |
| BTC, LTC | 1000 sat/vB | `maxFeeRate`, or an absolute `maxFee` (whole units) or `maxFeeSats` |
| BCH, DASH | 50 sat/byte | the same |
| ETH | `maxFeePerGas` at most 500 gwei, total fee at most 0.05 ETH, tip at most max(5 gwei, `maxFeePerGas` / 2) | `maxFeePerGas`, `maxPriorityFeePerGas` (wei), `maxFee` |
| TRON | `feeLimit` at most 150 TRX | `maxFeeLimit` (sun) |

A UTXO transaction with a version other than 1 or 2, a non-zero locktime (`allowLocktime: true` allows it), a repeated outpoint or a sighash type other than SIGHASH_ALL is refused (`0x41`, with FORKID, is accepted on BCH only).

## Hosted signing

For [hosted signing](https://docs.rarebl.com/guides/hosted-signing) the SDK builds an envelope v2 that names the chain, an expiry, a one-time id and what may be signed. The request needs the header `X-Rarebl-Accept-Risk: hosted-signing`.

~~~js
import { envelope } from './rarebl.mjs';

const signer = await rarebl.signerKey();                                       // {kid, publicKey, expiresAt}
const digests = reply.toSign.map((t) => t.digest);                             // after describeBuild passed
const forSign = await envelope.encrypt(signer, { privateKeys: [key], op: 'sign', chain: 'btc', digests });

const bind = envelope.bindOf('btc', [{ address: to, amount: '0.0015' }]);      // recipients, as base units
const forSend = await envelope.encrypt(signer, { privateKeys: [key], op: 'send', chain: 'btc', bind });
// POST /open/tx/sign or /open/tx/send with { ..., keys: { encrypted } } and the header above
~~~

An envelope is valid for at most 300 seconds and opens once. The signer refuses digests or outputs that are not the ones it names.

## Verify webhooks

~~~js
import { webhook } from './rarebl.mjs';

app.post('/hook', express.raw({ type: '*/*' }), (req, res) => {          // the RAW body, not parsed JSON
  if (!webhook.verify(process.env.RAREBL_SIGNING_SECRET, req.body, req.get('X-Rarebl-Signature'))) return res.sendStatus(400);
  const event = JSON.parse(req.body);                                     // deduplicate on X-Rarebl-Event-Id
  res.sendStatus(200);
});
~~~

The check is `HMAC-SHA256(secret, t + "." + body)` in constant time, with a 5 minute tolerance by default. See [Webhooks](https://docs.rarebl.com/guides/webhooks).

## Errors

API errors are typed (`ValidationError`, `ConflictError`, `UnprocessableError`, `RateLimitError` and others) and carry `code`, `reason` and `detail`, for example `API422` with reason `node_rejected`. A verification failure is a `VerifyError`, thrown before any signature is made.

## Security notes

- **Why local signing:** a private key that is never sent cannot be leaked, logged or subpoenaed from a server. The SDK never sends a key by itself; the only code that puts key material on the wire is `envelope.encrypt`, which you must call explicitly. See [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).
- **What `verify` protects against:** `signBuild` and `transfer` rebuild every digest (legacy, BIP143, BIP341 with SIGHASH_DEFAULT, BCH FORKID, EIP-1559 RLP and keccak, TRON `sha256(raw_data_hex)` plus a decode of TRX and TRC-20 transfers) from the unsigned transaction, and check outputs, amounts, change and fee against what *you* asked for. A compromised or buggy server therefore cannot make you sign a different payment. `expect` is mandatory in `signBuild` and `transfer` builds it from its arguments. `unsafeNoExpect: true` checks only internal consistency, and `verify: false` signs whatever digests the server sends: do not use either.
- **Legacy inputs:** the signature of a legacy p2pkh input (BTC, LTC, DASH) does not commit to its amount. The SDK therefore requires `unsigned.inputs[i].prevTx` (delivered by `tx/build`) or `prevTxs`, checks that it hashes to the outpoint and reads the amount from it; a reply without it, or with a different amount, is refused.
- **Known limits:** token decimals are never taken from the server: unknown tokens need an explicit `decimals`. TRON contracts other than TRX and TRC-20 `transfer` are refused.
- ECDSA signatures use RFC 6979 deterministic nonces and low-S, and are verified before they are returned. BIP340 (p2tr) signatures use fresh random auxiliary data; pass `deterministic: true` for reproducible output.
- **In a browser** the key lives in page memory: never load third-party scripts on a page that handles keys, and prefer a server you control for custody.
- **Hosted signing.** `envelope.encrypt` encrypts keys to the signer's X25519 key for `tx/sign` and `tx/send`; the key then leaves your machine, which local signing avoids: [Hosted signing](https://docs.rarebl.com/guides/hosted-signing).
- Keep keys in environment variables or a secret store, not in source. Test with small amounts first.

MIT licensed.

## Next

[Sign locally with the SDK](https://docs.rarebl.com/guides/sign-locally), [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction), [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses).

---

# Python SDK

The Python SDK (version 0.2.0) is a **single file**, `rarebl.py`, for Python 3.9 or later. It uses the **standard library only** (pure-Python secp256k1, Keccak-256 and the address encodings), so there is nothing to install besides the file. The optional hosted-signing envelope needs the `cryptography` package for AES-GCM and raises a clear error without it; nothing else in the SDK does.

It builds, verifies and signs transactions **on your machine**. Your private key never leaves the process unless you call the hosted-signing helper yourself.

## Download

| File | Size | SHA-256 |
| --- | --- | --- |
| [rarebl.py](https://docs.rarebl.com/sdk/python/rarebl.py) | 90.4 KB | `3e8f65c2c926a00d7ff916caf406b993e92509708d0611b431a171085abb4235` |

Requires: Python 3.9 or later; standard library only. All checksums are in [SHA256SUMS](https://docs.rarebl.com/sdk/SHA256SUMS). Check the file before you use it:

~~~bash
curl -O https://docs.rarebl.com/sdk/python/rarebl.py
sha256sum rarebl.py
~~~

## Install

Copy `rarebl.py` next to your code (or onto your `PYTHONPATH`) and import it:

~~~python
import rarebl
~~~

Registry publishing (PyPI `rarebl`) is planned; today you download the file and check its SHA-256 above.

## Ten lines: send BTC

~~~python
import rarebl

k = rarebl.keys.generate("btc", "p2wpkh")            # local, CSPRNG: {privateKey, wif, publicKey, address}
print("deposit address:", k["address"])             # fund it, then:

client = rarebl.Rarebl()                             # https://api.rarebl.com
txid = client.transfer(chain="btc", from_=k["address"],
                       to="bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm",
                       amount="0.001", key=k["privateKey"], priority="standard")
print("broadcast:", txid)
~~~

## Send USDT on TRON

~~~python
txid = client.transfer(chain="tron", from_=addr, to=recipient, amount="25",
                       token="TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", key=tron_key, feeLimit=15_000_000)
~~~

## `transfer()`

`client.transfer(chain, from_, to, amount, key, fee_rate=None, priority=None, token=None, decimals=None, verify=True, broadcast=True, auto_watch=True, change=None, max_fee=None, **extra)`

It builds with the API, **verifies the reply against what you asked for**, signs locally, then assembles and broadcasts. It returns the txid (or the `signed` object when `broadcast=False`).

- `amount` is a decimal string in whole units, or `"max"` on UTXO chains.
- `max_fee` caps the fee in base units (sats, wei or sun).
- `auto_watch=True`: on BTC, LTC and BCH it starts a watch on `from_` and waits for it to become active.
- `decimals` is needed for a token the SDK does not know. `**extra` passes more build fields, for example `feeLimit` (TRON) or `gasLimit`.
- `verify=True` is the default and should stay on: see below.

## Lower level: build, sign, assemble

~~~python
build = client.build({"chain": "btc", "from": [addr], "to": [{"address": dest, "amount": "0.0015"}], "priority": "standard"})
expect = {"to": {"address": dest, "amount": "0.0015"}}
rarebl.verify_build(build, expect=expect)                   # recompute every digest, raises VerifyError
sigs = rarebl.sign_build(build, key, expect=expect)         # expect is required; verifies again, then signs: [{index, signature, publicKey}]
res = client.assemble(build["unsigned"], sigs, broadcast=False)
client.broadcast("btc", res["signed"]["hex"], idempotency_key="payout-0001")
~~~

| Function | What it does |
| --- | --- |
| `keys.generate(chain, type=None)` | New keypair from the OS CSPRNG. |
| `keys.fromPrivate(chain, key, type=None)` | Public key and address of a key (hex or WIF). |
| `address.derive(chain, public_key, type)`, `address.validate(chain, address)` | Derive and validate addresses. |
| `sign_digest(digest_hex, private_key, algorithm, sighash_type=None, chain=None)` | One signature: ECDSA (DER + sighash byte), Schnorr (BIP340) or recoverable ECDSA (`r‖s‖v`). |
| `verify_build(build, pubkeys=None, expect=None)` | Recompute every digest; return True or raise `VerifyError`. `expect` pins outputs, amounts and a fee cap. |
| `sign_build(build, keys, verify=True, expect=None, now=None, unsafe_no_expect=False, deterministic=False, prev_txs=None)` | Verify and sign every digest; returns signatures for `assemble`. Raises `InputError` without `expect` (it must contain `to`). |
| `Rarebl(base_url, timeout)` | Client: `build`, `assemble`, `broadcast`, `estimate`, `decode`, `watch`, `utxos`, `status`, `nonce`, `validate`, `price`, `signer_key`, `outspends`, `transfer`. |
| `envelope.encrypt(signer_key, payload)` | Builds an envelope v2 for [hosted signing](https://docs.rarebl.com/guides/hosted-signing) only: `payload` is `{"privateKeys": [...], "op": "sign" or "send", "chain": ..., "digests": [...] or "bind": ...}`. `signer_key` is the whole reply of `signer_key()`. |
| `envelope.bind_of(chain, to, token=None, decimals=None)`, `envelope.seal`, `envelope.decrypt` | `bind_of` converts recipients to the base-unit `bind` of an `op: "send"` envelope; `decrypt` opens the `encryptedPrivateKey` of an [address/new](https://docs.rarebl.com/api/address/new) reply. |
| `webhook.verify(secret, raw_body, header, tolerance_sec=300)` | Check `X-Rarebl-Signature`. |

`expect` pins who is paid: `to` (`{address, amount | amountRaw}` or a list), `change` (extra change addresses; the input addresses always qualify), `token`, `decimals`, `opReturn`, `from`, `chain` and the fee caps below. `amount: "max"` must leave no change output. `unsafe_no_expect=True` signs without pinning the recipients (the fee caps still apply), and `verify=False` also needs it. `transfer()` always pins what you passed.

## Fee caps and defaults

When `expect` gives no cap, the SDK applies one. Override it through `expect`:

| Chain | Default | Override |
| --- | --- | --- |
| BTC, LTC | 1000 sat/vB | `maxFeeRate`, or an absolute `maxFee` (whole units) or `maxFeeSats` |
| BCH, DASH | 50 sat/byte | the same |
| ETH | `maxFeePerGas` at most 500 gwei, total fee at most 0.05 ETH, tip at most max(5 gwei, `maxFeePerGas` / 2) | `maxFeePerGas`, `maxPriorityFeePerGas` (wei), `maxFee`, `maxFeeRaw` |
| TRON | `feeLimit` at most 150 TRX | `maxFeeLimit` (sun) |

A UTXO transaction with a version other than 1 or 2, a non-zero locktime (`allowLocktime: True` allows it), a repeated outpoint or a sighash type other than SIGHASH_ALL is refused (`0x41`, with FORKID, is accepted on BCH only).

Legacy p2pkh inputs (BTC, LTC, DASH) must carry `unsigned.inputs[i].prevTx`, which `tx/build` delivers (or pass `prev_txs={txid: raw_hex}`): the SDK checks that it hashes to the outpoint and takes the amount from it.

## Hosted signing

For [hosted signing](https://docs.rarebl.com/guides/hosted-signing) the SDK builds an envelope v2 that names the chain, an expiry, a one-time id and what may be signed. The request needs the header `X-Rarebl-Accept-Risk: hosted-signing`.

~~~python
signer = client.signer_key()                                              # {kid, publicKey, expiresAt}
digests = [t["digest"] for t in build["toSign"]]                          # after verify_build passed
for_sign = rarebl.envelope.encrypt(signer, {"privateKeys": [key], "op": "sign", "chain": "btc", "digests": digests})

bind = rarebl.envelope.bind_of("btc", {"address": dest, "amount": "0.0015"})   # recipients, as base units
for_send = rarebl.envelope.encrypt(signer, {"privateKeys": [key], "op": "send", "chain": "btc", "bind": bind})

client.post("/open/tx/send", {"chain": "btc", "from": [addr], "to": [{"address": dest, "amount": "0.0015"}],
                              "keys": {"encrypted": for_send}}, headers={"X-Rarebl-Accept-Risk": "hosted-signing"})
~~~

An envelope is valid for at most 300 seconds and opens once.

## Verify webhooks

~~~python
ok = rarebl.webhook.verify(SIGNING_SECRET, raw_body_bytes, request.headers["X-Rarebl-Signature"], 300)
~~~

Pass the **raw** body, not re-serialised JSON. See [Webhooks](https://docs.rarebl.com/guides/webhooks).

## Errors

API errors raise `rarebl.ApiError` with `code`, `message`, `reason`, `detail` and `http_status` (for example code `API422`, reason `node_rejected`). `VerifyError` means a digest or output did not match, `KeyMismatchError` means a key does not own an input, `InputError` means a missing or invalid argument (for example signing without `expect`), `EnvelopeError` covers the envelope helper. All derive from `RareblError`.

## Command line

`python3 rarebl.py` is also a CLI (and the [shell SDK](https://docs.rarebl.com/sdks/shell) builds on it): `keygen`, `address`, `sign-digest`, `verify-build`, `sign-build`, `transfer` and `verify-webhook`. `sign-build` needs `--expect-to ADDR --expect-amount N` (or `--unsafe-no-expect`). Keys come from `--key-file`, `--key-env` or `--key-stdin`, **never from an argument**.

## Security notes

- **Why local signing:** a key that never leaves your process cannot be intercepted, logged or leaked by a service you call. See [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).
- **What `verify` protects against:** a server (or anything between you and it) returning a transaction that pays someone else, or digests that do not match. The SDK recomputes every digest and checks outputs, amounts, change and the fee before it signs, and `expect` is required so that the recipient is always pinned. `verify=False` signs the server's digests blindly and needs `unsafe_no_expect=True`: do not use it unless you have verified them another way.
- **Pure-Python crypto is not constant-time.** It gives no protection against local side-channel attacks. Use it on a machine you control (your own server or laptop), not on a shared host.
- ECDSA signatures are RFC 6979 deterministic, low-S, and verified after signing. BIP340 (p2tr) signatures use fresh random auxiliary data; pass `deterministic=True` for reproducible output.
- **Hosted signing:** `envelope.encrypt` builds the envelope for [hosted signing](https://docs.rarebl.com/guides/hosted-signing). The SDK never sends a key by itself; only calling that helper and posting its output does.
- Never put keys in source control, logs or command lines. Test with small amounts first.

## Next

[Sign locally with the SDK](https://docs.rarebl.com/guides/sign-locally), [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction), [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses), [Stuck transactions](https://docs.rarebl.com/guides/stuck-transactions).

---

# PHP SDK

The PHP SDK (version 0.2.0) is a **single file**, `Rarebl.php`, for **PHP 8.1 or later** with `ext-gmp` (and `ext-sodium` and `ext-openssl` for the envelope helper). All classes are in the namespace `Rarebl`: the client is `Rarebl\Rarebl`, signing is `Rarebl\Signer`, and there are `Keys`, `Address`, `Webhook` and `Envelope`. It builds, verifies and signs transactions **on your machine**; your private key never leaves the process. secp256k1 runs on GMP in pure PHP, with Keccak-256 and the address encodings included.

## Download

| File | Size | SHA-256 |
| --- | --- | --- |
| [Rarebl.php](https://docs.rarebl.com/sdk/php/Rarebl.php) | 110.7 KB | `5784caa72a1c89abd6a386911cac6008d8726757de3456e2606ff986592c142c` |

Requires: PHP 8.1 or later with ext-gmp (ext-sodium for envelopes). All checksums are in [SHA256SUMS](https://docs.rarebl.com/sdk/SHA256SUMS). Check the file before you use it:

~~~bash
curl -O https://docs.rarebl.com/sdk/php/Rarebl.php
sha256sum Rarebl.php
~~~

## Install

Copy `Rarebl.php` into your project and require it:

~~~php
<?php
require __DIR__ . '/Rarebl.php';
~~~

Registry publishing (Packagist `rarebl/sdk`) comes later; today you download the file and check its SHA-256 above. Check that GMP is loaded with `php -m | grep gmp`.

## Ten lines: send BTC

~~~php
<?php
require 'Rarebl.php';

$k = Rarebl\Keys::generate('btc', 'p2wpkh');          // local, CSPRNG: privateKey, wif, publicKey, address
echo "deposit address: {$k['address']}\n";            // fund it, then:

$client = new Rarebl\Rarebl();                        // https://api.rarebl.com
$txid = $client->transfer([
    'chain' => 'btc', 'from' => $k['address'], 'to' => 'bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm',
    'amount' => '0.001', 'key' => $k['privateKey'], 'priority' => 'standard',
]);
echo "broadcast: $txid\n";
~~~

## Send USDT on TRON

~~~php
<?php
$txid = $client->transfer([
    'chain' => 'tron', 'from' => $addr, 'to' => $recipient, 'amount' => '25',
    'token' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', 'key' => $tronKey, 'feeLimit' => 15000000,
]);
~~~

## `transfer()`

`$client->transfer([...])` runs **build, verify, sign locally, assemble and broadcast** and returns the txid. Amounts are **decimal strings** in whole units: never PHP floats.

## Lower level: build, sign, assemble

~~~php
<?php
$build = $client->build(['chain' => 'btc', 'from' => [$addr], 'to' => [['address' => $dest, 'amount' => '0.0015']], 'priority' => 'standard']);
$expect = ['to' => ['address' => $dest, 'amount' => '0.0015']];
Rarebl\Signer::verifyBuild($build, null, $expect);                      // recompute every digest, throws VerifyException on any mismatch
$signatures = Rarebl\Signer::signBuild($build, $key, ['expect' => $expect]);   // expect is required; verifies, then signs
$res = $client->assemble($build['unsigned'], $signatures, false);
$client->broadcast('btc', $res['signed']['hex'], 'payout-0001');
~~~

| Function | What it does |
| --- | --- |
| `Keys::generate`, `Keys::fromPrivate` | Local key generation and import. |
| `Address::derive`, `Address::validate` | Derive and validate addresses. |
| `Signer::signDigest` | One signature: DER + sighash byte, BIP340 Schnorr, or recoverable `r‖s‖v`. |
| `Signer::verifyBuild($build, $pubkeys, $expect, $nowMs, $prevTxs)` | Recompute every digest and check outputs, amounts, change and the fee. |
| `Signer::signBuild($build, $keys, $opts)` | Verify, then sign every digest. `$opts` is `['expect' => ..., 'unsafeNoExpect' => false, 'verify' => true, 'deterministic' => false, 'nowMs' => null, 'prevTxs' => null]`; it throws `InputException` without `expect['to']`. The old positional form is gone. |
| `build`, `assemble`, `broadcast`, `watch`, `utxos`, `status`, `signerKey`, `post`, `transfer` | The API calls, on `Rarebl\Rarebl`. |
| `Envelope::encrypt($signerKey, $payload)` | Builds an envelope v2 for [hosted signing](https://docs.rarebl.com/guides/hosted-signing) only, through `ext-sodium` (X25519) and `openssl_encrypt` (AES-256-GCM). `$signerKey` is the whole reply of `signerKey()`. |
| `Envelope::bindOf($chain, $to, $token, $decimals)`, `Envelope::decrypt` | `bindOf` converts recipients to the base-unit `bind` of an `op: 'send'` envelope; `decrypt` opens the `encryptedPrivateKey` of an [address/new](https://docs.rarebl.com/api/address/new) reply. |
| `Webhook::verify` | Check `X-Rarebl-Signature`. |

`$expect` pins who is paid: `to` (`['address', 'amount' | 'amountRaw']` or a list), `change` (extra change addresses; the input addresses always qualify), `token`, `decimals`, `opReturn`, `from`, `chain` and the fee caps below. `amount: "max"` must leave no change output. `'unsafeNoExpect' => true` signs without pinning the recipients (the fee caps still apply), and `'verify' => false` also needs it. `transfer()` always pins what you passed.

## Fee caps and defaults

When `expect` gives no cap, the SDK applies one. Override it through `expect`:

| Chain | Default | Override |
| --- | --- | --- |
| BTC, LTC | 1000 sat/vB | `maxFeeRate`, or an absolute `maxFee` (whole units) or `maxFeeSats` |
| BCH, DASH | 50 sat/byte | the same |
| ETH | `maxFeePerGas` at most 500 gwei, total fee at most 0.05 ETH, tip at most max(5 gwei, `maxFeePerGas` / 2) | `maxFeePerGas`, `maxPriorityFeePerGas` (wei), `maxFee`, `maxFeeRaw` |
| TRON | `feeLimit` at most 150 TRX | `maxFeeLimit` (sun) |

A UTXO transaction with a version other than 1 or 2, a non-zero locktime (`'allowLocktime' => true` allows it), a repeated outpoint or a sighash type other than SIGHASH_ALL is refused (`0x41`, with FORKID, is accepted on BCH only).

Legacy p2pkh inputs (BTC, LTC, DASH) must carry `unsigned.inputs[i].prevTx`, which `tx/build` delivers (or pass `'prevTxs' => [txid => rawHex]`): the SDK checks that it hashes to the outpoint and takes the amount from it.

## Hosted signing

For [hosted signing](https://docs.rarebl.com/guides/hosted-signing) the SDK builds an envelope v2 that names the chain, an expiry, a one-time id and what may be signed. The request needs the header `X-Rarebl-Accept-Risk: hosted-signing`.

~~~php
<?php
use Rarebl\Envelope;

$signer = $client->signerKey();                                            // ['kid', 'publicKey', 'expiresAt']
$digests = array_column($build['toSign'], 'digest');                       // after verifyBuild passed
$forSign = Envelope::encrypt($signer, ['privateKeys' => [$key], 'op' => 'sign', 'chain' => 'btc', 'digests' => $digests]);

$bind = Envelope::bindOf('btc', ['address' => $dest, 'amount' => '0.0015']);   // recipients, as base units
$forSend = Envelope::encrypt($signer, ['privateKeys' => [$key], 'op' => 'send', 'chain' => 'btc', 'bind' => $bind]);

$client->post('/open/tx/send', ['chain' => 'btc', 'from' => [$addr], 'to' => [['address' => $dest, 'amount' => '0.0015']],
                                'keys' => ['encrypted' => $forSend]], ['X-Rarebl-Accept-Risk' => 'hosted-signing']);
~~~

An envelope is valid for at most 300 seconds and opens once.

## Verify webhooks

~~~php
<?php
$raw = file_get_contents('php://input');               // the RAW body
$ok = Rarebl\Webhook::verify(getenv('RAREBL_WEBHOOK_SECRET'), $raw, $_SERVER['HTTP_X_RAREBL_SIGNATURE'] ?? '', 300);
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($raw, true);                      // deduplicate on X-Rarebl-Event-Id
http_response_code(200);
~~~

See [Webhooks](https://docs.rarebl.com/guides/webhooks).

## Errors

API errors become `ApiException` (`->apiCode`, `->reason`, `->detail`, `->httpStatus`), for example `API422` and `node_rejected`. `VerifyException` is thrown before any signature is made, `KeyMismatchException` means a key does not own an input, `InputException` means a missing or invalid argument (for example signing without `expect`), and `EnvelopeException` covers the envelope helper. All extend `RareblException`.

## Security notes

- **Why local signing:** a key that never leaves your process cannot be intercepted, logged or leaked by a service you call: [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).
- **What `verify` protects against:** a server (or anything in between) returning a transaction that pays someone else, or digests that do not match. The SDK recomputes every digest and checks outputs, amounts, change and the fee before signing, and `expect` is required so that the recipient is always pinned. Turning verification off must be explicit (`'verify' => false` with `'unsafeNoExpect' => true`) and means you trust the server's digests blindly.
- **Pure-PHP crypto is not constant-time.** Run signing on a machine you control, not on a shared host.
- ECDSA signatures are RFC 6979 deterministic, low-S, and verified after signing. BIP340 (p2tr) signatures use fresh random auxiliary data; pass `'deterministic' => true` for reproducible output.
- Do not log request bodies on a server that handles keys, and keep keys out of web-accessible directories.
- `Envelope::encrypt` builds the envelope for [hosted signing](https://docs.rarebl.com/guides/hosted-signing). The SDK never sends a key by itself.

## Next

[Sign locally with the SDK](https://docs.rarebl.com/guides/sign-locally), [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction), [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses).

---

# Shell SDK

`rarebl` (version 0.2.0) is a command line tool, a bash script built on `curl`, `jq` and the [Python SDK](https://docs.rarebl.com/sdks/python) (`rarebl.py`). It generates keys, signs and sends transactions, and verifies webhooks from a terminal or a cron job, with **local signing**: the private key is used on your machine only.

## Download

| File | Size | SHA-256 |
| --- | --- | --- |
| [rarebl](https://docs.rarebl.com/sdk/shell/rarebl) | 11.2 KB | `9e8bf0f697a84fe426826275b0ae413a8215bc9b34838cc2b719c4dade77cbc7` |

Requires: bash, curl, jq and the Python SDK. All checksums are in [SHA256SUMS](https://docs.rarebl.com/sdk/SHA256SUMS). Check the file before you use it:

~~~bash
curl -O https://docs.rarebl.com/sdk/shell/rarebl
sha256sum rarebl
~~~

## Install

~~~bash
mkdir -p ~/.local/bin && cd ~/.local/bin
curl -O https://docs.rarebl.com/sdk/shell/rarebl
curl -O https://docs.rarebl.com/sdk/python/rarebl.py
sha256sum rarebl rarebl.py                 # compare with the checksums on this page and in SHA256SUMS
chmod +x rarebl
~~~

You need `bash`, `curl`, `jq` and Python 3.9 or later. Run `rarebl help` for the full list. The Python CLI (`python3 rarebl.py <command>`) offers the same signing commands under the names `sign-build` and `verify-build`.

## Keys never go on the command line

Give a key through **a file, an environment variable or stdin**. A key in an argument would show up in your shell history and in the process list.

| Option | Reads the key from |
| --- | --- |
| `--key-file ./btc.key` | A file (one key per line is allowed). Use `chmod 600`. |
| `--key-env NAME` | An environment variable. |
| `--key-stdin` | The first line of stdin. |

## Generate a key

~~~bash
rarebl keygen --chain btc --type p2wpkh      # prints {privateKey, wif, publicKey, address}; generated locally
~~~

Save the private key to a file with restricted permissions and keep it out of source control.

## Ten lines: send BTC

~~~bash
rarebl keygen --chain btc --type p2wpkh > key.json
jq -r .privateKey key.json > btc.key && chmod 600 btc.key
ADDR=$(jq -r .address key.json); echo "fund: $ADDR"

rarebl transfer --chain btc --from "$ADDR" \
  --to bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm \
  --amount 0.001 --priority standard --key-file ./btc.key
~~~

It prints the txid. Add `--no-broadcast` to print the signed transaction instead.

## Send USDT on TRON

~~~bash
rarebl transfer --chain tron --from "$TADDR" --to "$TRECIPIENT" --amount 25 \
  --token TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t --key-env TRON_KEY
~~~

## Sign digests yourself

~~~bash
rarebl build --chain btc --from "$ADDR" --to bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm --amount 0.0015 --priority standard > build.json
rarebl sign build.json --key-file ./btc.key \
  --expect-to bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm --expect-amount 0.0015 > signatures.json   # verifies every digest and the payment, then signs
rarebl assemble build.json signatures.json --broadcast
~~~

`sign` refuses to run without `--expect-to` and `--expect-amount`: the recipient must be pinned. It refuses a digest it cannot recompute, a payment that differs from the expectation, change sent elsewhere and an absurd fee. `--unsafe-no-expect` signs without pinning the recipient (the fee caps still apply), and `--no-verify` signs blindly and needs it. Add `--token T --decimals N` for token transfers and `--deterministic` for reproducible BIP340 signatures. [Assemble](https://docs.rarebl.com/api/tx/assemble) is the API call behind `rarebl assemble`.

Default fee caps: 1000 sat/vB on BTC and LTC, 50 sat/byte on BCH and DASH, ETH 500 gwei and 0.05 ETH, TRON 150 TRX. Legacy p2pkh inputs (BTC, LTC, DASH) must carry their previous transaction (`prevTx`), which `tx/build` delivers. `rarebl transfer` always pins what you passed; add `--max-fee N` to cap the fee.

## Other commands

| Command | Use |
| --- | --- |
| `rarebl address --chain btc --validate ADDRESS` | Validate an address. |
| `rarebl status --chain btc TXID`, `rarebl watch --chain btc ADDRESS`, `rarebl utxos --chain btc ADDRESS`, `rarebl price btc,eth` | Read the API. |
| `rarebl address --chain btc --type p2wpkh --key-file K` | Derive the address of a key. |
| `rarebl verify-webhook --header "$SIG" --body-file body.json` | Check `X-Rarebl-Signature` (secret from `RAREBL_WEBHOOK_SECRET` or `--secret-file`). Exit code 0 when valid, 1 when not. |

## Verify a webhook from a script

~~~bash
RAREBL_WEBHOOK_SECRET=... rarebl verify-webhook --header "$HTTP_X_RAREBL_SIGNATURE" --body-file - < body.raw && echo ok
~~~

See [Webhooks](https://docs.rarebl.com/guides/webhooks).

## Exit codes

`0` success, `1` (verify-webhook) invalid signature, `2` SDK or usage error (for example a verification failure), `3` the API answered with an error (for example `API422`).

## Security notes

- **Why local signing:** the key stays on your machine: [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).
- **What verification protects against:** a server returning a transaction that pays someone else or digests that do not match: [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction). It is on by default and the expectation is required.
- The signing code is pure Python and **not constant-time**: use it on a machine you control.
- Keep key files `chmod 600`, out of source control and out of backups you do not trust. Test with small amounts first.
- This tool signs locally and has no command for hosted signing; the envelope helpers are in the [JavaScript](https://docs.rarebl.com/sdks/js), [Python](https://docs.rarebl.com/sdks/python) and [PHP](https://docs.rarebl.com/sdks/php) SDKs: [Hosted signing](https://docs.rarebl.com/guides/hosted-signing).

---

# Rarebl Explorer

The **Rarebl Explorer** is the website for browsing the same data that the API serves: [explorer.rarebl.com](https://explorer.rarebl.com).

It is built on the same chain layer as the Open API, so what you see there and what you get from the API always agree. Use it to look at a block, transaction or address by eye while you build, and to cross-check what your integration returns.

## What you can do there

- Browse the latest blocks and transactions of Bitcoin, Litecoin, Bitcoin Cash, Dash, Ethereum and TRON.
- Open a block, a transaction or an address and see the same fields the API returns.
- Watch the mempool and the network fees.
- Search any height, hash, address or token name, or paste a link from another explorer (the same search as [Search](https://docs.rarebl.com/api/search/query)). Results appear as you type, with keyboard navigation and recent searches.

## Explorer and API side by side

| Explorer | Open API |
| --- | --- |
| Block page | [Block](https://docs.rarebl.com/api/block/get) |
| Transaction page | [Transaction](https://docs.rarebl.com/api/tx/get) and [Transaction status](https://docs.rarebl.com/api/tx/status) |
| Address page | [Address](https://docs.rarebl.com/api/address/balance) and [Address transactions](https://docs.rarebl.com/api/address/transactions) |
| Mempool page | [Mempool](https://docs.rarebl.com/api/tx/mempool) |
| Gas tracker | [Recommended fees](https://docs.rarebl.com/api/fees/recommended) |
| Search box | [Search](https://docs.rarebl.com/api/search/query) |

The explorer is a website for people. For programs, use the Open API at `https://api.rarebl.com/open`: it is documented, versioned and rate limited per IP, with a stable [response envelope](https://docs.rarebl.com/responses-and-codes).

[Open the Explorer](https://explorer.rarebl.com)

---

# Changelog

What changed in the Rarebl Open API and these docs, newest first.

## Every reply now carries its request id in meta

15 November 2026 · API Update, Improvement

Every Open API reply ends with a `meta` object: `meta.requestid` (the same value as the `X-Request-Id` header) and `meta.notices`. Existing fields are unchanged.

### The meta object (additive)

- Every `/open/*` reply, success or error, gains a last field `meta`: `{ "requestid": "0123456789abcdef", "notices": [] }`.
- `meta.requestid` is 16 hex characters and equals the `X-Request-Id` header, which is still sent. Quote it when you contact support.
- `meta.notices` is always an array, empty today. A notice is `{ "code", "message", "docs"? }`; clients can ignore it.
- `status`, `code`, `message`, `data` and `go` are unchanged. Explorer backend replies, webhook deliveries and WebSocket messages have no `meta`.

## Search that understands what you paste, and docs search that finds the exact line

15 November 2026 · API Update, Improvement

The search endpoint now ranks every plausible match with a confidence and a reason, reads addresses in every format with checksum checks, accepts token names, explorer links and payment links, and explains a miss. The documentation search covers every page, endpoint, field, error code and SDK method, with typo tolerance.

### Search endpoint (additive)

- New response fields: `results[].confidence`, `reason`, `verified`, `path`, `rank` and `token`, plus `best`, `ambiguous`, `query`, `suggestions`, `unavailable` and `mode`. The original `chain`, `type`, `id` and `label` are unchanged.
- New parameters: `mode` (`full`, or `fast` for as-you-type suggestions with no node call), `chain` and `limit`.
- Every address format is validated by checksum: base58, bech32 and bech32m (taproot), CashAddr with or without `bitcoincash:`, EIP-55 for Ethereum, TRON base58 and 41-hex. A wrong checksum gives no result and an `invalid_checksum` suggestion.
- Token names and symbols (`USDT`, `tether`), chain names and contract prefixes match with typo tolerance. New result types: `contract` and `chain`.
- Links from mempool.space, etherscan, tronscan, blockchair and others, and `bitcoin:`, `ethereum:` and other payment links, are reduced to the identifier inside. Private keys are refused and never echoed.
- Heights and hashes are checked on every candidate chain in parallel, inside a 4 second budget; a node that does not answer is listed in `unavailable`.

### Documentation search

- Full text over every page and section, endpoint, parameter, response field, error code (`API200` to `API502`) and reason, and SDK method, with synonyms, typo tolerance and highlighted snippets.
- Press Ctrl K (or Cmd K). Arrow keys move, Enter opens, Esc closes. The index loads the first time you open search.

## SDK 0.2.0 and hosted-signing envelope v2

15 November 2026 · Breaking Change, API Update

The SDKs now require the expected recipient when you sign, apply default fee caps and check the previous transaction of legacy inputs. Hosted signing uses an envelope v2 that is bound to a chain, an operation and what may be signed.

### SDK 0.2.0

- **`expect` is required** when you sign a build yourself: `signBuild` (JavaScript), `sign_build` (Python), `Signer::signBuild` (PHP, now `signBuild($build, $keys, ["expect" => ...])`) and `rarebl sign --expect-to --expect-amount`. `transfer()` is unchanged. An explicit `unsafeNoExpect` signs without pinning the recipient.
- **Default fee caps** when `expect` gives none: 1000 sat/vB (BTC, LTC), 50 sat/byte (BCH, DASH), ETH `maxFeePerGas` 500 gwei and 0.05 ETH in total, TRON `feeLimit` 150 TRX. A non-zero locktime is refused unless `allowLocktime` is set.
- **Legacy p2pkh inputs** (BTC, LTC, DASH) carry `prevTx` in `tx/build` replies; the SDKs check that it hashes to the input and read the amount from it.
- BIP340 (p2tr) signatures use random auxiliary data; pass `deterministic` for reproducible output.

### Hosted signing

- **Envelope v2** (`envelope.encrypt`) names the chain, the operation, an expiry of at most 300 seconds and a one-time id. `op: "sign"` lists the digests; `op: "send"` lists the recipients and amounts. Envelope v1 is refused with `bad_envelope`.
- New reasons on [tx/sign](https://docs.rarebl.com/api/tx/sign) and [tx/send](https://docs.rarebl.com/api/tx/send): `bad_envelope`, `envelope_expired`, `envelope_replayed`, `digest_not_bound`, `outputs_not_bound` and `chain_mismatch`.
- The [signer key](https://docs.rarebl.com/api/tx/signer-key) is refused 7 days after its `expiresAt`; fetch it again when you get `bad_envelope`.

## Recommended fees for every chain

15 November 2026 · Improvement

A clearer home for fees: Recommended fees gives the fastest, medium and normal fee for every chain — miner fees in sat/vB on BTC, LTC, BCH and DASH, gas in Gwei on ETH and the energy price in sun on TRON.

### What changed

- New path [`/open/fees/recommended`](https://docs.rarebl.com/api/fees/recommended), in the new **Gas and miner fees** section. `fast`, `standard` and `slow` are the fastest, medium and normal speeds; they match `priority` in [Build a transaction](https://docs.rarebl.com/api/tx/build).
- `/open/gas/oracle` keeps working and returns the same reply.
- [Token](https://docs.rarebl.com/api/token/info) moved into the **Stats** section of the reference.

## Open API v2: transactions, signing SDKs, webhooks, streams, market data

14 November 2026 · New Feature

Build, sign and broadcast transactions on all six chains, with SDKs that sign on your machine, plus address tools, webhooks, a WebSocket stream and market prices. No API keys: every endpoint is keyless and limited per IP.

### What is new

- **Transactions:** [Build](https://docs.rarebl.com/api/tx/build), [Assemble](https://docs.rarebl.com/api/tx/assemble), [Broadcast](https://docs.rarebl.com/api/tx/broadcast), [Decode](https://docs.rarebl.com/api/tx/decode), [Estimate](https://docs.rarebl.com/api/tx/estimate), [Output spend status](https://docs.rarebl.com/api/tx/outspends) and [Signer key](https://docs.rarebl.com/api/tx/signer-key). Three ways to send: [sign locally with the SDK](https://docs.rarebl.com/guides/sign-locally) (recommended), [sign the digests](https://docs.rarebl.com/guides/send-a-transaction), or [hosted signing](https://docs.rarebl.com/guides/hosted-signing).
- **Hosted signing:** [Sign](https://docs.rarebl.com/api/tx/sign), [Send](https://docs.rarebl.com/api/tx/send) and [New address](https://docs.rarebl.com/api/address/new), for callers that cannot sign locally; they need the header `X-Rarebl-Accept-Risk: hosted-signing`. Try It is disabled for them.
- **Addresses:** [Validate](https://docs.rarebl.com/api/address/validate), [Watch](https://docs.rarebl.com/api/address/watch), [UTXOs](https://docs.rarebl.com/api/address/utxos), [Nonce](https://docs.rarebl.com/api/address/nonce) and [Resources](https://docs.rarebl.com/api/address/resources).
- **Webhooks:** [create](https://docs.rarebl.com/api/hooks/create), get, update, pause, resume, delete, deliveries, test and replay, with signed deliveries and retries: [Webhooks](https://docs.rarebl.com/guides/webhooks).
- **Market data:** [Prices](https://docs.rarebl.com/api/market/price), [Tickers](https://docs.rarebl.com/api/market/tickers), [History](https://docs.rarebl.com/api/market/history), [Assets](https://docs.rarebl.com/api/market/assets) and [FX](https://docs.rarebl.com/api/market/fx): reference prices, not trading rates.
- **WebSocket stream:** [wss://api.rarebl.com/ws](https://docs.rarebl.com/api/websocket) for blocks, fees, address, transaction and token channels.
- **SDKs:** single-file [JavaScript](https://docs.rarebl.com/sdks/js), [Python](https://docs.rarebl.com/sdks/python), [PHP](https://docs.rarebl.com/sdks/php) and [shell](https://docs.rarebl.com/sdks/shell) SDKs with local keys, signing, `transfer()` and webhook verification, each with a SHA-256.
- **Guides:** step-by-step walkthroughs: [Quickstart](https://docs.rarebl.com/quickstart), [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction), [Sign locally with the SDKs](https://docs.rarebl.com/guides/sign-locally), [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses), [Webhooks](https://docs.rarebl.com/guides/webhooks), [Live data over WebSocket](https://docs.rarebl.com/guides/websocket), [Market data and fees](https://docs.rarebl.com/guides/market-data), [Stuck transactions](https://docs.rarebl.com/guides/stuck-transactions) and [Errors and rate limits](https://docs.rarebl.com/guides/handle-errors).

### What changed

- [Rate limits](https://docs.rarebl.com/rate-limits) now have classes (read, compute, write, watch, hooks, stream), still per IP and keyless.
- New codes `API422` and `API403`, and new reasons such as `not_watched`: [Responses & codes](https://docs.rarebl.com/responses-and-codes).

### Known limits

The Ethereum node is still syncing, and a watch on BTC, LTC or BCH takes time to bootstrap. See [Coverage and limits](https://docs.rarebl.com/limits-today).

## Open API v1: 13 read-only endpoints

14 November 2026 · New Feature

Read-only blockchain data for Bitcoin, Litecoin, Bitcoin Cash, Dash, Ethereum and TRON from Rarebl's own nodes, with no API key.

### What is new

- **Stats:** [Chains](https://docs.rarebl.com/api/stats/chains) and [Live stats](https://docs.rarebl.com/api/stats/live) (heads of all six chains, refreshed about every 2 seconds).
- **Blocks:** [Latest blocks](https://docs.rarebl.com/api/block/latest) and [Block](https://docs.rarebl.com/api/block/get).
- **Transactions:** [Transaction](https://docs.rarebl.com/api/tx/get), [Transaction status](https://docs.rarebl.com/api/tx/status) and [Mempool](https://docs.rarebl.com/api/tx/mempool).
- **Addresses:** [Address](https://docs.rarebl.com/api/address/balance), [Address transactions](https://docs.rarebl.com/api/address/transactions) and [Address tokens](https://docs.rarebl.com/api/address/tokens).
- **Tokens:** [Token](https://docs.rarebl.com/api/token/info) for ETH and TRON.
- **Gas and miner fees:** [Recommended fees](https://docs.rarebl.com/api/fees/recommended) in sat/vB, Gwei and sun.
- **Search:** [Search](https://docs.rarebl.com/api/search/query) for any height, hash or address.

### How it works

- Every endpoint is `GET` with query parameters or `POST` with a JSON body, at `https://api.rarebl.com/open/<module>/<action>`.
- No key is needed: clients are limited per IP to 5 requests per second, burst 20. `X-API-KEY` is reserved for keyed plans.
- Every reply uses the `API*` envelope. See [Responses & codes](https://docs.rarebl.com/responses-and-codes).
- CORS is open, so browsers can call the API directly, including the Try It panel in these docs.

### Known limits

A few capabilities depend on work that is still in progress.

- Address transactions are available on DASH only until the history index is built; BTC, LTC and BCH balances are `null` with `balanceStatus: "index_pending"` until then.
- TRON history starts on 2026-09-08.
- The Ethereum node is still syncing, so some ETH calls answer `API409` or `API502`.
- Details and reasons are on [Coverage and limits](https://docs.rarebl.com/limits-today).

---

# FAQ

Answers to common questions about the Rarebl Open API.

## Getting started

### Which SDKs are there?

Single-file SDKs for [JavaScript](https://docs.rarebl.com/sdks/js), [Python](https://docs.rarebl.com/sdks/python), [PHP](https://docs.rarebl.com/sdks/php) and a [shell](https://docs.rarebl.com/sdks/shell) tool. They generate keys, build and verify transactions, sign locally and verify webhook signatures. Each download page shows its SHA-256.

### Do webhooks need an account?

No. `hooks/create` returns a management token and a signing secret, shown once. Deliveries are signed with `X-Rarebl-Signature`. See [Webhooks](https://docs.rarebl.com/guides/webhooks).

### Do I need an API key?

No. The API is keyless and has no accounts or billing: clients are limited per IP, by rate class. The `X-API-KEY` header is reserved and ignored. See [Authentication](https://docs.rarebl.com/authentication).

### Can I call the API from a browser?

Yes. The API sends `Access-Control-Allow-Origin: *`, so browser apps can call it directly, and the Try It panel on every endpoint page does exactly that.

### Should I use GET or POST?

Both work with identical parameters. `GET` with query parameters is simplest. `POST` takes the same parameters as a JSON body.

### Is the API stable?

The Open API (v1 and v2) is live at `https://api.rarebl.com`. The endpoint paths and the response envelope are the contract, and the [Changelog](https://docs.rarebl.com/changelog) records every change.

### Is there a Postman collection?

Yes: download [the collection](https://docs.rarebl.com/collections/rarebl-api.postman_collection.json) and [the environment](https://docs.rarebl.com/collections/rarebl-live.postman_environment.json) and import both into Postman. It covers every endpoint, with folders by group, POST bodies and headers, and variables for the webhook id and token.

## Data and chains

### Which chains are supported?

Bitcoin (`btc`), Litecoin (`ltc`), Bitcoin Cash (`bch`), Dash (`dash`), Ethereum (`eth`, with ERC-20, ERC-721 and ERC-1155 tokens) and TRON (`tron`, with TRC-10, TRC-20 and TRC-721 tokens). See [Chains & units](https://docs.rarebl.com/chains-and-units).

### Where does the data come from?

From Rarebl's own full nodes. There are no third-party chain APIs behind the Open API, and the [Rarebl Explorer](https://docs.rarebl.com/explorer) uses the same data, so the two always agree.

### Can I send transactions?

Yes, with Open API v2: [Build](https://docs.rarebl.com/api/tx/build), sign, [Assemble](https://docs.rarebl.com/api/tx/assemble) and [Broadcast](https://docs.rarebl.com/api/tx/broadcast), on all six chains including USDT on ETH and TRON. The safest way is to sign on your own machine with an [SDK](https://docs.rarebl.com/sdks/python). Smart-contract calls beyond token transfers, logs and an RPC proxy are not part of the Open API. See [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).

### Do I have to send my private key to the API?

Hosted signing (`tx/sign`, `tx/send`, `address/new`) sends your private key to Rarebl over TLS, and needs the header `X-Rarebl-Accept-Risk: hosted-signing`. Signing locally with an SDK keeps keys on your side and is recommended. See [Hosted signing](https://docs.rarebl.com/guides/hosted-signing).

### Are the market prices trading rates?

No. They are reference prices aggregated from public exchange feeds (the median of fresh sources), not Rarebl trading rates. See [Market data and fees](https://docs.rarebl.com/guides/market-data).

## Limits and freshness

### What are the rate limits?

Per IP and by class: reads 5 per second (burst 20), compute 2 per second (burst 10), write calls such as broadcast 6 per minute (burst 3, 300 per day), watch 30 per minute, hooks 10 per minute and 3 stream connections. Past a limit you get `API429` and a `Retry-After` header. See [Rate limits](https://docs.rarebl.com/rate-limits).

### How fresh is the data?

Chain heads in [Live stats](https://docs.rarebl.com/api/stats/live) are at most about 2 seconds old. See [Data freshness](https://docs.rarebl.com/data-freshness) for the other endpoints, confirmations and reorg depths.

### How many confirmations should I wait for?

That is your policy. The API treats data deeper than the reorg depth as settled: 6 blocks on BTC, LTC, BCH and DASH, 64 on ETH and 20 on TRON. See [Track a deposit until it confirms](https://docs.rarebl.com/guides/track-a-deposit).

### Why do I get API409?

The data is not available yet on that chain. `data.reason` says why: the history index is still being built (`history_unavailable`), the ETH node is still syncing (`tx_index_pending`), a TRON height is before 2026-09-08 (`before_history_start`), or there is no mempool view (`no_mempool_view`). See [Coverage and limits](https://docs.rarebl.com/limits-today).

### Why is a Bitcoin, Litecoin or Bitcoin Cash balance null?

Those balances need the history index, which is still being built. The address reply says `balanceStatus: "index_pending"`. `null` means unknown, not zero. DASH, ETH and TRON balances are exact.

## Support

### Where do I get help?

Email [hello@rarebl.com](mailto:hello@rarebl.com) or message us on [WhatsApp](https://wa.me/233551648687). Include the request you sent (with the `chain` and the hash or address) and the full reply, `code` and `message` included.

### Do these docs track me?

We count page views without cookies; no personal data. The counts use no cookies or stored identifiers and respect Do Not Track and Global Privacy Control. Nothing you type into Try It, no request body, address or hash is ever sent to analytics.

### Do I need a Rarebl account?

Not to use the Open API. You can [sign up](https://app.rarebl.com/#!/signup) for the Rarebl app, which is a separate product from this API.

---

# API reference

# API reference

Rarebl Open API (v1 and v2): 42 HTTP endpoints for BTC, LTC, BCH, DASH, ETH and TRON, at `https://api.rarebl.com/open/<module>/<action>`, plus a [WebSocket stream](https://docs.rarebl.com/api/websocket). v1 reads accept `GET` with query parameters or `POST` with a JSON body; v2 writes are `POST` with a JSON body. No API key is needed: clients are limited per IP by rate class.

Each endpoint page documents its parameters, headers, a request example, realistic responses and the error codes it can return. Shared response shapes are on [Data types](https://docs.rarebl.com/data-types).

### Stats

| Endpoint | Method | Path | Rate class | Description |
| --- | --- | --- | --- | --- |
| [Chains](https://docs.rarebl.com/api/stats/chains) | `GET` / `POST` | `/open/stats/chains` | read | List the six supported chains with their identity, units, current tip, health and which features each one supports today. |
| [Live stats](https://docs.rarebl.com/api/stats/live) | `GET` / `POST` | `/open/stats/live` | read | One cheap call with the head of every chain: tip, mempool size and the current fee. Refreshed about every 2 seconds, so it is the one to poll. |
| [Token](https://docs.rarebl.com/api/token/info) | `GET` / `POST` | `/open/token/info` | read | Metadata of a token contract on ETH or TRON: standard, name, symbol, decimals and total supply. |

### Blocks

| Endpoint | Method | Path | Rate class | Description |
| --- | --- | --- | --- | --- |
| [Latest blocks](https://docs.rarebl.com/api/block/latest) | `GET` / `POST` | `/open/block/latest` | read | The newest blocks of a chain, newest first, with a cursor to page back in time. |
| [Block](https://docs.rarebl.com/api/block/get) | `GET` / `POST` | `/open/block/get` | read | One block by height or hash, with its chain-specific details and a page of its transactions. |

### Transactions

| Endpoint | Method | Path | Rate class | Description |
| --- | --- | --- | --- | --- |
| [Transaction](https://docs.rarebl.com/api/tx/get) | `GET` / `POST` | `/open/tx/get` | read | Full detail of one transaction by hash: status, block, amounts and fee, plus inputs and outputs (UTXO chains) or sender, gas, token transfers and logs (ETH and TRON). |
| [Transaction status](https://docs.rarebl.com/api/tx/status) | `GET` / `POST` | `/open/tx/status` | read | A small, fast status check for one transaction: pending, success or failed, its block, confirmations and time. Built for polling a deposit until it confirms. |
| [Mempool](https://docs.rarebl.com/api/tx/mempool) | `GET` / `POST` | `/open/tx/mempool` | read | Unconfirmed transactions the node currently sees, newest first, with the mempool size. |
| [Build a transaction](https://docs.rarebl.com/api/tx/build) | `POST` | `/open/tx/build` | compute | Builds an unsigned transaction on any chain and returns the digests to sign. The API supplies UTXOs or nonce and fees; your keys never leave you. |
| [Assemble a signed transaction](https://docs.rarebl.com/api/tx/assemble) | `POST` | `/open/tx/assemble` | compute | Inserts your signatures into an unsigned transaction from tx/build, verifies them, and can broadcast the result in the same call. |
| [Broadcast a transaction](https://docs.rarebl.com/api/tx/broadcast) | `POST` | `/open/tx/broadcast` | write | Sends a fully signed transaction to the network through Rarebl's own nodes, with pre-checks and an idempotency key. |
| [Decode a transaction](https://docs.rarebl.com/api/tx/decode) | `POST` | `/open/tx/decode` | compute | Decodes a raw transaction (signed or unsigned) into the v1 Tx shape, with status `unsent`, so you can check what you are about to send. |
| [Estimate a transaction](https://docs.rarebl.com/api/tx/estimate) | `POST` | `/open/tx/estimate` | compute | Estimates the fee of a transaction without building digests. It takes the same body as tx/build. |
| [Output spend status](https://docs.rarebl.com/api/tx/outspends) | `GET` | `/open/tx/outspends` | read | For each output of a UTXO transaction, whether it is spent, by which transaction, and whether the spend is still in the mempool. |
| [Signer public key](https://docs.rarebl.com/api/tx/signer-key) | `GET` | `/open/tx/signer-key` | read | The X25519 public key you encrypt private keys to when you use hosted signing. Only the signer process can read what you encrypt to it. |

### Hosted signing

| Endpoint | Method | Path | Rate class | Description |
| --- | --- | --- | --- | --- |
| [Sign a transaction (hosted)](https://docs.rarebl.com/api/tx/sign) | `POST` | `/open/tx/sign` | write | Sends private keys to Rarebl, which signs an unsigned transaction in memory and forgets the keys. It never broadcasts. |
| [Build, sign and send (hosted)](https://docs.rarebl.com/api/tx/send) | `POST` | `/open/tx/send` | write | One call that builds, signs with the keys you send, and broadcasts. |
| [New address and key (hosted)](https://docs.rarebl.com/api/address/new) | `POST` | `/open/address/new` | write | Generates a new keypair inside the signer, never stores it, and returns it once. The SDKs can also generate keys locally (`keys.generate`). |

### Addresses

| Endpoint | Method | Path | Rate class | Description |
| --- | --- | --- | --- | --- |
| [Address](https://docs.rarebl.com/api/address/balance) | `GET` / `POST` | `/open/address/balance` | read | Balance and summary of an address: validity, type, balance, totals received and sent, transaction count and chain-specific details. |
| [Address transactions](https://docs.rarebl.com/api/address/transactions) | `GET` / `POST` | `/open/address/transactions` | read | The transactions of an address, newest first, with a cursor to page back in time. |
| [Address tokens](https://docs.rarebl.com/api/address/tokens) | `GET` / `POST` | `/open/address/tokens` | read | Token balances held by an ETH or TRON address: known tokens such as USDT and USDC, plus TRC-10 assets on TRON. |
| [Validate an address](https://docs.rarebl.com/api/address/validate) | `GET` | `/open/address/validate` | compute | Checks that an address is well formed for a chain and returns its type and normalized form. For ETH it also tells whether the address is a contract. |
| [Watch addresses](https://docs.rarebl.com/api/address/watch) | `POST` | `/open/address/watch` | watch | Starts tracking BTC, LTC or BCH addresses (their UTXOs and activity) so that UTXOs, balances and webhooks become exact. |
| [Address UTXOs](https://docs.rarebl.com/api/address/utxos) | `GET` | `/open/address/utxos` | read | The unspent outputs and balance of an address, for sweeps and payouts. BTC, LTC and BCH addresses must be watched and active; DASH uses its node index. |
| [Address nonce (ETH)](https://docs.rarebl.com/api/address/nonce) | `GET` | `/open/address/nonce` | read | The latest and pending transaction count of an Ethereum address, to set the nonce of the next transaction. |
| [Address resources (TRON)](https://docs.rarebl.com/api/address/resources) | `GET` | `/open/address/resources` | read | The energy and bandwidth of a TRON account, and its frozen balances, to know whether a transfer burns TRX. |

### Gas and miner fees

| Endpoint | Method | Path | Rate class | Description |
| --- | --- | --- | --- | --- |
| [Recommended fees](https://docs.rarebl.com/api/fees/recommended) | `GET` / `POST` | `/open/fees/recommended` | read | Recommended fees for every chain at three speeds — fastest, medium and normal: the miner fee on BTC, LTC, BCH and DASH (sat/vB), the gas price on ETH (Gwei) and the energy price on TRON (sun). |

### Search

| Endpoint | Method | Path | Rate class | Description |
| --- | --- | --- | --- | --- |
| [Search](https://docs.rarebl.com/api/search/query) | `GET` / `POST` | `/open/search/query` | read | Find out what a pasted string is: a block height, a transaction or block hash, an address in any format, a token name or a contract, or a link from another explorer. Every plausible match comes back ranked, with a confidence and a reason. |

### Webhooks

| Endpoint | Method | Path | Rate class | Description |
| --- | --- | --- | --- | --- |
| [Create a webhook](https://docs.rarebl.com/api/hooks/create) | `POST` | `/open/hooks/create` | hooks | Creates a webhook subscription. There are no accounts: the reply carries a management token and a signing secret, both shown once. |
| [Get a webhook](https://docs.rarebl.com/api/hooks/get) | `GET` | `/open/hooks/get` | read | Reads a subscription. Secrets are not returned again. |
| [Update a webhook](https://docs.rarebl.com/api/hooks/update) | `POST` | `/open/hooks/update` | hooks | Changes fields of a subscription, for example its URL or confirmation threshold. |
| [Pause a webhook](https://docs.rarebl.com/api/hooks/pause) | `POST` | `/open/hooks/pause` | hooks | Stops deliveries without deleting the subscription. |
| [Resume a webhook](https://docs.rarebl.com/api/hooks/resume) | `POST` | `/open/hooks/resume` | hooks | Restarts deliveries of a paused subscription. |
| [Delete a webhook](https://docs.rarebl.com/api/hooks/delete) | `POST` | `/open/hooks/delete` | hooks | Deletes a subscription permanently. |
| [Webhook deliveries](https://docs.rarebl.com/api/hooks/deliveries) | `GET` | `/open/hooks/deliveries` | read | The last 100 delivery attempts of a subscription, to debug your endpoint. |
| [Send a test event](https://docs.rarebl.com/api/hooks/test) | `POST` | `/open/hooks/test` | hooks | Sends a signed sample event to your URL so you can test signature verification. |
| [Replay an event](https://docs.rarebl.com/api/hooks/replay) | `POST` | `/open/hooks/replay` | hooks | Re-sends a past event to your URL. |

### Market

| Endpoint | Method | Path | Rate class | Description |
| --- | --- | --- | --- | --- |
| [Prices](https://docs.rarebl.com/api/market/price) | `GET` | `/open/market/price` | read | Reference prices aggregated from public exchange feeds: the median of fresh sources, outliers more than 2% from the median excluded. Not Rarebl trading rates. |
| [Tickers](https://docs.rarebl.com/api/market/tickers) | `GET` | `/open/market/tickers` | read | The individual exchange tickers behind a price. |
| [Price history](https://docs.rarebl.com/api/market/history) | `GET` | `/open/market/history` | read | OHLCV candles for an asset. |
| [Assets](https://docs.rarebl.com/api/market/assets) | `GET` | `/open/market/assets` | read | The assets with prices: symbol, name, chain, token contract and decimals. |
| [FX rates](https://docs.rarebl.com/api/market/fx) | `GET` | `/open/market/fx` | read | Foreign-exchange reference rates, for example usd to ghs and ngn. |

---

# Chains

`GET https://api.rarebl.com/open/stats/chains` or `POST https://api.rarebl.com/open/stats/chains`

List the six supported chains with their identity, units, current tip, health and which features each one supports today.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/stats/chains"`

## Parameters

This endpoint takes no parameters.

## Responses

### API200 (HTTP 200): OK

The six chains, in a fixed order (btc, ltc, bch, dash, eth, tron).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "chains": [
      {
        "id": "btc",
        "name": "Bitcoin",
        "symbol": "BTC",
        "decimals": 8,
        "kind": "utxo",
        "status": "ok",
        "tip": {
          "height": 975854,
          "hash": "00000000000000000000ac4918a89711fb90ab487b7e21d02995f39d88a83b9c",
          "time": "2026-11-14T22:25:13Z"
        },
        "historyFrom": null,
        "features": {
          "addressHistory": false,
          "addressBalance": false,
          "tokens": false,
          "mempool": true,
          "internalTxs": false
        }
      },
      {
        "id": "ltc",
        "name": "Litecoin",
        "symbol": "LTC",
        "decimals": 8,
        "kind": "utxo",
        "status": "ok",
        "tip": {
          "height": 3213201,
          "hash": "e7b72ef9f34b8f61b2b5dabec238088bf1198fe9779df88f5b1a87c8e3f276e7",
          "time": "2026-11-14T22:38:19Z"
        },
        "historyFrom": null,
        "features": {
          "addressHistory": false,
          "addressBalance": false,
          "tokens": false,
          "mempool": true,
          "internalTxs": false
        }
      },
      {
        "id": "bch",
        "name": "Bitcoin Cash",
        "symbol": "BCH",
        "decimals": 8,
        "kind": "utxo",
        "status": "ok",
        "tip": {
          "height": 977391,
          "hash": "00000000000000000130fbfa0ec402f4fca4b414cdff8d264e4caa225c9ea81e",
          "time": "2026-11-14T22:39:19Z"
        },
        "historyFrom": null,
        "features": {
          "addressHistory": false,
          "addressBalance": false,
          "tokens": false,
          "mempool": true,
          "internalTxs": false
        }
      },
      {
        "id": "dash",
        "name": "Dash",
        "symbol": "DASH",
        "decimals": 8,
        "kind": "utxo",
        "status": "ok",
        "tip": {
          "height": 2572373,
          "hash": "0000000000000008ef6f834cf172cb739f5542f0ad1f7103c9a22d65be56f064",
          "time": "2026-11-14T22:37:02Z"
        },
        "historyFrom": null,
        "features": {
          "addressHistory": true,
          "addressBalance": true,
          "tokens": false,
          "mempool": true,
          "internalTxs": false
        }
      },
      {
        "id": "eth",
        "name": "Ethereum",
        "symbol": "ETH",
        "decimals": 18,
        "kind": "account",
        "status": "lagging",
        "tip": null,
        "historyFrom": null,
        "features": {
          "addressHistory": false,
          "addressBalance": true,
          "tokens": true,
          "mempool": true,
          "internalTxs": false
        }
      },
      {
        "id": "tron",
        "name": "TRON",
        "symbol": "TRX",
        "decimals": 6,
        "kind": "account",
        "status": "lagging",
        "tip": {
          "height": 88007289,
          "hash": "00000000053ee279103116c09576a469acc68fe6ab27ffa89d3358ca59a3fc78",
          "time": "2026-11-14T22:36:06Z"
        },
        "historyFrom": "2026-09-08T17:50:00Z",
        "features": {
          "addressHistory": false,
          "addressBalance": true,
          "tokens": true,
          "mempool": true,
          "internalTxs": false
        }
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.chains[].id` | string | Chain id: btc, ltc, bch, dash, eth or tron. |
| `data.chains[].kind` | string | `utxo` or `account`. |
| `data.chains[].decimals` | integer | Decimals of the native unit (8, 18 or 6). |
| `data.chains[].status` | string | `ok`, `lagging` or `down` (the node did not answer). |
| `data.chains[].tip` | object \| null | Latest block `{height, hash, time}`; null while the node is syncing or down. |
| `data.chains[].historyFrom` | string \| null | Earliest block time that can be shown. TRON starts on 2026-09-08; null where full history is available. |
| `data.chains[].features` | object | Booleans: `addressHistory`, `addressBalance`, `tokens`, `mempool`, `internalTxs`. Check these before relying on an endpoint for a chain. |

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Use `features` to see what is available per chain today (for example `addressHistory` is true only for DASH until the history index is built).
- The reply is cached for about 10 seconds. For a fast-moving view of the chain heads, use [Live stats](https://docs.rarebl.com/api/stats/live).
- The example is a real reply from 2026-11-14. ETH was `lagging` with a null `tip` (its node was still syncing) and TRON was `lagging` because its newest block was a few minutes old.

---

# Live stats

`GET https://api.rarebl.com/open/stats/live` or `POST https://api.rarebl.com/open/stats/live`

One cheap call with the head of every chain: tip, mempool size and the current fee. Refreshed about every 2 seconds, so it is the one to poll.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/stats/live"`

## Parameters

This endpoint takes no parameters.

## Responses

### API200 (HTTP 200): OK

Heads of all six chains in the same order as Chains.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "serverTime": "2026-11-14T22:39:43Z",
    "chains": [
      {
        "id": "btc",
        "status": "ok",
        "tip": {
          "height": 975854,
          "hash": "00000000000000000000ac4918a89711fb90ab487b7e21d02995f39d88a83b9c",
          "time": "2026-11-14T22:25:13Z"
        },
        "mempool": {
          "count": 70161,
          "bytes": 25261120
        },
        "fee": {
          "unit": "sat/vB",
          "standard": "0.13"
        },
        "checkedAt": "2026-11-14T22:39:43Z"
      },
      {
        "id": "ltc",
        "status": "ok",
        "tip": {
          "height": 3213201,
          "hash": "e7b72ef9f34b8f61b2b5dabec238088bf1198fe9779df88f5b1a87c8e3f276e7",
          "time": "2026-11-14T22:38:19Z"
        },
        "mempool": {
          "count": 172,
          "bytes": 50642
        },
        "fee": {
          "unit": "sat/vB",
          "standard": "1"
        },
        "checkedAt": "2026-11-14T22:39:43Z"
      },
      {
        "id": "bch",
        "status": "ok",
        "tip": {
          "height": 977391,
          "hash": "00000000000000000130fbfa0ec402f4fca4b414cdff8d264e4caa225c9ea81e",
          "time": "2026-11-14T22:39:19Z"
        },
        "mempool": {
          "count": 2,
          "bytes": 1163
        },
        "fee": {
          "unit": "sat/vB",
          "standard": "1"
        },
        "checkedAt": "2026-11-14T22:39:43Z"
      },
      {
        "id": "dash",
        "status": "ok",
        "tip": {
          "height": 2572373,
          "hash": "0000000000000008ef6f834cf172cb739f5542f0ad1f7103c9a22d65be56f064",
          "time": "2026-11-14T22:37:02Z"
        },
        "mempool": {
          "count": 26,
          "bytes": 18576
        },
        "fee": {
          "unit": "sat/vB",
          "standard": "1"
        },
        "checkedAt": "2026-11-14T22:39:43Z"
      },
      {
        "id": "eth",
        "status": "lagging",
        "tip": null,
        "mempool": null,
        "fee": null,
        "checkedAt": "2026-11-14T22:39:43Z"
      },
      {
        "id": "tron",
        "status": "lagging",
        "tip": {
          "height": 88007289,
          "hash": "00000000053ee279103116c09576a469acc68fe6ab27ffa89d3358ca59a3fc78",
          "time": "2026-11-14T22:36:06Z"
        },
        "mempool": {
          "count": 0,
          "bytes": null
        },
        "fee": {
          "unit": "sun",
          "standard": "100"
        },
        "checkedAt": "2026-11-14T22:39:43Z"
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.serverTime` | string | When the reply was built (ISO 8601 UTC). |
| `data.chains[].id` | string | Chain id. |
| `data.chains[].status` | string | `ok`, `lagging` or `down`. Height 0 (syncing) shows as lagging with a null tip. |
| `data.chains[].tip` | object \| null | Latest block `{height, hash, time}`. |
| `data.chains[].mempool` | object \| null | `{count, bytes}`; null where the chain has no mempool view (ETH today). |
| `data.chains[].fee` | object \| null | `{unit, standard}` in the same unit as Gas oracle. |
| `data.chains[].checkedAt` | string | When the backend last asked this node (ISO 8601 UTC). |

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Each chain head is cached for at most about 2 seconds. A slow or down node never delays the others: that chain is reported `down` for a few seconds.
- Poll no faster than once per 2 seconds. Compare `tip.hash` between polls to detect a new block, then fetch only what you need.
- See [Data freshness](https://docs.rarebl.com/data-freshness) and the guide [Market data and fees](https://docs.rarebl.com/guides/market-data).

---

# Latest blocks

`GET https://api.rarebl.com/open/block/latest` or `POST https://api.rarebl.com/open/block/latest`

The newest blocks of a chain, newest first, with a cursor to page back in time.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/block/latest?chain=btc&limit=2"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. One of: btc, ltc, bch, dash, eth, tron. |
| `before` | integer | No | Return blocks below this height (exclusive). Pass the previous reply's `next`. Block height, 0 or higher. |
| `limit` | integer | No | Number of blocks to return. 1 to 25 (larger values are capped at 25) Default 10. |

## Responses

### API200 (HTTP 200): OK

A page of block summaries.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "items": [
      {
        "height": 975852,
        "hash": "0000000000000000000106d2c49ad20a447077c0ee2a8000a0bf7dca0df81fc5",
        "time": "2026-11-14T22:21:59Z",
        "txCount": 2749,
        "size": 1630627,
        "miner": "32i1m6gNcSHwiPX9nfTNXVjme9j5DU8y5g",
        "reward": "3.14466985",
        "fees": "0.01966985"
      },
      {
        "height": 975851,
        "hash": "0000000000000000000019616694441cd8af0ea40612fea00423994106ff3339",
        "time": "2026-11-14T22:18:52Z",
        "txCount": 3914,
        "size": 1553016,
        "miner": "1K6KoYC69NnafWJ7YgtrpwJxBLiijWqwa6",
        "reward": "3.17394194",
        "fees": "0.04894194"
      }
    ],
    "next": 975851
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.items[]` | BlockSummary | `height`, `hash`, `time`, `txCount`, `size`, `miner`, `reward`, `fees` (see Data types). |
| `data.next` | integer \| null | The lowest height of this page. Pass it back as `before` for the next page; null at the first block available. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Unknown or missing chain.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Amounts in `reward` and `fees` are exact decimal strings in the chain's native unit.
- On ETH, `reward` and `fees` are null in this list for blocks nobody has opened yet: [Block](https://docs.rarebl.com/api/block/get) fills them. On TRON, `reward` is null and `size` is null.
- For TRON, `next` is null at the first block the node holds (history starts 2026-09-08).

---

# Block

`GET https://api.rarebl.com/open/block/get` or `POST https://api.rarebl.com/open/block/get`

One block by height or hash, with its chain-specific details and a page of its transactions.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/block/get?chain=btc&id=975851&limit=2"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. One of: btc, ltc, bch, dash, eth, tron. |
| `id` | string | Yes | Block height or block hash. Digits for a height; 64 hex characters for a hash (ETH hashes carry 0x). |
| `page` | integer | No | Page of the block's transactions, 1-based. 1 or higher Default 1. |
| `limit` | integer | No | Transactions per page. 1 to 100 Default 25. |

## Responses

### API200 (HTTP 200): OK

The block, a page of its transactions and the paging totals. The `details` list is shortened here.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "block": {
      "height": 975851,
      "hash": "0000000000000000000019616694441cd8af0ea40612fea00423994106ff3339",
      "time": "2026-11-14T22:18:52Z",
      "txCount": 3914,
      "size": 1553016,
      "miner": "1K6KoYC69NnafWJ7YgtrpwJxBLiijWqwa6",
      "reward": "3.17394194",
      "fees": "0.04894194",
      "prevHash": "00000000000000000000aab9d0593887d52c5c910227ddbf04a87fb91227800a",
      "nextHash": "0000000000000000000106d2c49ad20a447077c0ee2a8000a0bf7dca0df81fc5",
      "confirmations": 2,
      "details": [
        {
          "key": "difficulty",
          "label": "Difficulty",
          "value": "134823837323272.70",
          "kind": "number"
        },
        {
          "key": "bits",
          "label": "Bits",
          "value": "17021673",
          "kind": "text"
        },
        {
          "key": "nonce",
          "label": "Nonce",
          "value": 2693129303,
          "kind": "number"
        },
        {
          "key": "merkleRoot",
          "label": "Merkle root",
          "value": "c1ecbc059fa5cf6fa14433ef6dc20036d1c6ff9c04b01f19b0af0a4aaca0b8e3",
          "kind": "hash"
        },
        {
          "key": "weight",
          "label": "Weight",
          "value": 3997815,
          "kind": "number",
          "unit": "WU"
        },
        {
          "key": "subsidy",
          "label": "Subsidy",
          "value": "3.125",
          "kind": "amount",
          "unit": "BTC"
        }
      ]
    },
    "txs": [
      {
        "hash": "f1bd58223f137a63659cb2e8f05bf4c362494b41b4586536626c363137d1b6b6",
        "block": 975851,
        "time": "2026-11-14T22:18:52Z",
        "status": "success",
        "from": null,
        "to": "1K6KoYC69NnafWJ7YgtrpwJxBLiijWqwa6",
        "value": "3.17394194",
        "fee": null,
        "method": "coinbase",
        "inputs": 1,
        "outputs": 7
      },
      {
        "hash": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
        "block": 975851,
        "time": "2026-11-14T22:18:52Z",
        "status": "success",
        "from": null,
        "to": "37dD2C3QMSSVLPAyQVZo8ZLG53AgUDbcuc",
        "value": "0.022609",
        "fee": null,
        "method": null,
        "inputs": 1,
        "outputs": 2
      }
    ],
    "page": 1,
    "pages": 1957,
    "total": 3914
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.block` | Block | BlockSummary fields plus `prevHash`, `nextHash`, `confirmations` and chain-specific `details` rows. |
| `data.txs[]` | TxSummary | Transactions of the requested page. |
| `data.page` | integer | The page returned. |
| `data.pages` | integer | Total pages at this `limit`. |
| `data.total` | integer | Total transactions in the block. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Unknown or missing chain.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The block does not exist on that chain.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Block not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API409 (HTTP 409): Conflict

TRON only: the height is below `historyFrom` (2026-09-08).

```json
{
  "status": 0,
  "code": "API409",
  "message": "This node holds TRON blocks from #86072637 (2026-09-08T17:50:00Z).",
  "data": {
    "reason": "before_history_start"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- The `details` rows depend on the chain: difficulty, bits, nonce and merkle root on UTXO chains; ChainLock on Dash; gas used/limit, base fee, burnt fees and withdrawals on ETH; the witness on TRON.
- On Litecoin and Bitcoin Cash some per-transaction fields (`from`, `fee`) are null in block lists; fetch [Transaction](https://docs.rarebl.com/api/tx/get) for the resolved values.
- `nextHash` is null on the chain tip.

---

# Transaction

`GET https://api.rarebl.com/open/tx/get` or `POST https://api.rarebl.com/open/tx/get`

Full detail of one transaction by hash: status, block, amounts and fee, plus inputs and outputs (UTXO chains) or sender, gas, token transfers and logs (ETH and TRON).

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/tx/get?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. One of: btc, ltc, bch, dash, eth, tron. |
| `id` | string | Yes | The transaction hash. 64 hex characters, lowercase; ETH hashes carry 0x. |

## Responses

### API200 (HTTP 200): OK

The transaction. This UTXO example is shortened; ETH and TRON transactions carry an `account` object instead of `utxo`.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "tx": {
      "chain": "btc",
      "hash": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
      "status": "success",
      "block": 975851,
      "blockHash": "0000000000000000000019616694441cd8af0ea40612fea00423994106ff3339",
      "time": "2026-11-14T22:18:52Z",
      "confirmations": 2,
      "value": "0.022609",
      "fee": "0.000448",
      "utxo": {
        "size": 223,
        "vsize": 142,
        "weight": 565,
        "locktime": 975850,
        "version": 2,
        "rbf": true,
        "coinbase": false,
        "inputs": [
          {
            "txid": "15f0189bea2a90b1b7232e96e9d9728ac72187133ce2ad33f2ee464f45cb8fa8",
            "vout": 1,
            "address": "bc1qsxcc56fruvcrwvxpf8ulg572rtt2vn34vtyjlt",
            "value": "0.023057",
            "scriptType": "witness_v0_keyhash",
            "sequence": 4294967293,
            "coinbase": false
          }
        ],
        "outputs": [
          {
            "n": 0,
            "address": "37dD2C3QMSSVLPAyQVZo8ZLG53AgUDbcuc",
            "value": "0.01",
            "scriptType": "scripthash",
            "opReturn": null,
            "spent": false
          },
          {
            "n": 1,
            "address": "bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q",
            "value": "0.012609",
            "scriptType": "witness_v0_keyhash",
            "opReturn": null,
            "spent": true
          }
        ]
      },
      "details": [
        {
          "key": "status",
          "label": "Status",
          "value": "Confirmed",
          "kind": "text"
        },
        {
          "key": "block",
          "label": "Block",
          "value": 975851,
          "kind": "block"
        },
        {
          "key": "inputTotal",
          "label": "Total input",
          "value": "0.023057",
          "kind": "amount",
          "unit": "BTC"
        },
        {
          "key": "fee",
          "label": "Fee",
          "value": "0.000448",
          "kind": "amount",
          "unit": "BTC"
        },
        {
          "key": "feeRate",
          "label": "Fee rate",
          "value": "315.49",
          "kind": "number",
          "unit": "sat/vB",
          "hint": "Fee divided by virtual size."
        }
      ]
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.tx.status` | string | `success`, `failed` or `pending`. |
| `data.tx.block` | integer \| null | Block height; null while pending. |
| `data.tx.confirmations` | integer | Blocks on top of the transaction's block, counting that block (0 while pending). |
| `data.tx.value` | string | Native amount moved (UTXO: total output). |
| `data.tx.fee` | string \| null | Native fee; null when it cannot be resolved (for example Litecoin MWEB). |
| `data.tx.utxo` | object | UTXO chains only: size, vsize, weight, locktime, version, rbf, coinbase, `inputs[]` and `outputs[]`. |
| `data.tx.account` | object | ETH and TRON only: from, to, nonce, gas fields, decoded method, `tokenTransfers[]`, `logs[]` and TRON `tron` resources. |
| `data.tx.details` | DetailRow[] | Overview rows picked and ordered by the backend. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `id`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Transaction id must be a 64-character hash.",
  "data": {
    "param": "id"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The transaction does not exist on that chain.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Transaction not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API409 (HTTP 409): Conflict

ETH only: the node is still building its transaction index, so older transactions cannot be looked up yet.

```json
{
  "status": 0,
  "code": "API409",
  "message": "The node is still indexing old transactions. Try again later.",
  "data": {
    "reason": "tx_index_pending"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Amounts are decimal strings in whole units (never floats). ETH gas prices are in Gwei; TRON fees are in TRX.
- Litecoin (MWEB) hides amounts: `fee` is null and unresolved input `value`s are null, never `0`.
- Litecoin and Bitcoin Cash resolve input addresses and values (and so `fee`) here only, for at most 50 inputs. `outputs[].spent` is looked up for at most 50 outputs, else null.
- To wait for confirmations, poll the lighter [Transaction status](https://docs.rarebl.com/api/tx/status).

---

# Transaction status

`GET https://api.rarebl.com/open/tx/status` or `POST https://api.rarebl.com/open/tx/status`

A small, fast status check for one transaction: pending, success or failed, its block, confirmations and time. Built for polling a deposit until it confirms.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/tx/status?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. One of: btc, ltc, bch, dash, eth, tron. |
| `id` | string | Yes | The transaction hash. 64 hex characters, lowercase; ETH hashes carry 0x. |

## Responses

### API200 (HTTP 200): OK

A confirmed transaction.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "hash": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
    "status": "success",
    "block": 975851,
    "confirmations": 2,
    "time": "2026-11-14T22:18:52Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.hash` | string | The transaction hash. |
| `data.status` | string | `success`, `failed` or `pending`. |
| `data.block` | integer \| null | Block height; null while pending. |
| `data.confirmations` | integer | 0 while pending. |
| `data.time` | string \| null | Block time (ISO 8601 UTC); null while pending. |

### API200 (HTTP 200): OK (pending)

A transaction that is in the mempool and not yet in a block.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "hash": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
    "status": "pending",
    "block": null,
    "confirmations": 0,
    "time": null
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `id`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Transaction id must be a 64-character hash.",
  "data": {
    "param": "id"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The transaction does not exist on that chain.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Transaction not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API409 (HTTP 409): Conflict

ETH only: the node is still building its transaction index.

```json
{
  "status": 0,
  "code": "API409",
  "message": "The node is still indexing old transactions. Try again later.",
  "data": {
    "reason": "tx_index_pending"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- `failed` means the transaction was included in a block but reverted (ETH and TRON). UTXO transactions are `success` once in a block.
- Compare `confirmations` with your own threshold. See [Data freshness](https://docs.rarebl.com/data-freshness) for reorg depths and the guide [Track a deposit until it confirms](https://docs.rarebl.com/guides/track-a-deposit).

---

# Mempool

`GET https://api.rarebl.com/open/tx/mempool` or `POST https://api.rarebl.com/open/tx/mempool`

Unconfirmed transactions the node currently sees, newest first, with the mempool size.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/tx/mempool?chain=btc&limit=2"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. One of: btc, ltc, bch, dash, eth, tron. |
| `limit` | integer | No | Transactions to return. 1 to 100 Default 25. |

## Responses

### API200 (HTTP 200): OK

Mempool size and a sample of pending transactions.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "count": 68328,
    "bytes": 24527873,
    "items": [
      {
        "hash": "313da871f52272bbf0fa799af9d46dca0efbc329570dff0a4e30e6dd3f4eb6d4",
        "block": null,
        "time": null,
        "status": "pending",
        "from": null,
        "to": "bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm",
        "value": "0.000363",
        "fee": null,
        "method": null,
        "inputs": 1,
        "outputs": 2,
        "firstSeen": "2026-11-14T22:23:08Z"
      },
      {
        "hash": "cf106e2e83ff9f7ac23bef28795db36132c14cde7e0b1c3c070c9378598d6a8d",
        "block": null,
        "time": null,
        "status": "pending",
        "from": null,
        "to": "bc1p8ah4ltyv9w2z00ynvulgwxjv8z78mgr5lectl7ey7kacahx8ltrs37wlvd",
        "value": "0.00195024",
        "fee": null,
        "method": null,
        "inputs": 3,
        "outputs": 6,
        "firstSeen": "2026-11-14T22:23:08Z"
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.count` | integer \| null | Transactions in the mempool. |
| `data.bytes` | integer \| null | Mempool size in bytes. |
| `data.items[]` | TxSummary | Pending transactions, newest first. Each has `firstSeen` (ISO 8601 UTC): when the backend first saw it. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Unknown or missing chain.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API409 (HTTP 409): Conflict

The node has no pending-transaction view for that chain right now (for example ETH while its node has no pending block).

```json
{
  "status": 0,
  "code": "API409",
  "message": "This node has no pending transaction view.",
  "data": {
    "reason": "no_mempool_view"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- UTXO chains return a sample from the node's mempool, not a complete list: the Bitcoin mempool holds tens of thousands of transactions. `count` is the real size.
- On pending UTXO items `fee` and `from` are null. TRON returns at most 50 transactions from the node's pending list.
- The reply is cached for about 3 seconds and shared between callers.

---

# Address

`GET https://api.rarebl.com/open/address/balance` or `POST https://api.rarebl.com/open/address/balance`

Balance and summary of an address: validity, type, balance, totals received and sent, transaction count and chain-specific details.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/address/balance?chain=btc&address=XgNx6VFjYhSKPxXcjcPvad61DPSQhdiJDT"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. One of: btc, ltc, bch, dash, eth, tron. |
| `address` | string | Yes | The address to look up. A valid address for the chain. BCH accepts CashAddr (with or without prefix) and legacy. |

## Responses

### API200 (HTTP 200): OK

Balance of a Dash address (exact).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "address": {
      "chain": "dash",
      "address": "XgNx6VFjYhSKPxXcjcPvad61DPSQhdiJDT",
      "valid": true,
      "type": "p2pkh",
      "balance": "10.0001",
      "balanceStatus": "exact",
      "received": "10.0001",
      "sent": "0",
      "txCount": 1,
      "tokens": [],
      "isContract": null,
      "history": {
        "available": true,
        "reason": null
      },
      "details": [
        {
          "key": "immature",
          "label": "Immature balance",
          "value": "0",
          "kind": "amount",
          "unit": "DASH"
        },
        {
          "key": "utxos",
          "label": "Unspent outputs",
          "value": 1,
          "kind": "number"
        }
      ]
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.address.valid` | boolean | Whether the address is well formed for the chain. |
| `data.address.type` | string \| null | p2pkh, p2sh, p2wpkh, p2tr, cashaddr, eoa, contract, tron-account and so on. |
| `data.address.balance` | string \| null | Native balance. Null until the history index exists on BTC, LTC and BCH. |
| `data.address.balanceStatus` | string | `exact`, or `index_pending` for BTC, LTC and BCH until the history index exists. |
| `data.address.received / sent / txCount` | string \| null | Lifetime totals, when known. |
| `data.address.tokens[]` | object[] | Known tokens held (ETH and TRON). |
| `data.address.history` | object | `{available, reason}`: whether address history can be listed. |
| `data.address.details` | DetailRow[] | ETH nonce; TRON energy, bandwidth and frozen resources; Dash unspent output count. |

### API200 (HTTP 200): OK (index pending)

A Bitcoin address: the balance is not available until the history index exists.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "address": {
      "chain": "btc",
      "address": "1K6KoYC69NnafWJ7YgtrpwJxBLiijWqwa6",
      "valid": true,
      "type": "p2pkh",
      "balance": null,
      "balanceStatus": "index_pending",
      "received": null,
      "sent": null,
      "txCount": null,
      "tokens": [],
      "isContract": null,
      "history": {
        "available": false,
        "reason": "index_pending"
      },
      "details": []
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `address`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Invalid BTC address.",
  "data": {
    "param": "address"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Today the balance is exact on DASH, ETH and TRON. On BTC, LTC and BCH it is `null` with `balanceStatus: "index_pending"` until the history index is built. Treat that as "unknown", not zero.
- Never display `null` as `0`. See [Coverage and limits](https://docs.rarebl.com/limits-today).

---

# Address transactions

`GET https://api.rarebl.com/open/address/transactions` or `POST https://api.rarebl.com/open/address/transactions`

The transactions of an address, newest first, with a cursor to page back in time.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/address/transactions?chain=btc&address=XgNx6VFjYhSKPxXcjcPvad61DPSQhdiJDT&limit=2"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. One of: btc, ltc, bch, dash, eth, tron. |
| `address` | string | Yes | The address to list. |
| `cursor` | string | No | Opaque cursor from the previous reply's `next`. |
| `limit` | integer | No | Transactions per page. 1 to 100 Default 25. |

## Responses

### API200 (HTTP 200): OK

A page of transactions for a Dash address.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "items": [
      {
        "hash": "8873c69e78499a49913042b743f3a96f28c520f3c0d66db47682f19dd9c43032",
        "block": 2572369,
        "time": "2026-11-14T22:18:18Z",
        "status": "success",
        "from": "Xf9atpnTdh2j8mQP2yaJkR9wWSp2vaorzE",
        "to": "XgNx6VFjYhSKPxXcjcPvad61DPSQhdiJDT",
        "value": "50.0005",
        "fee": "0",
        "method": null,
        "inputs": 5,
        "outputs": 5
      }
    ],
    "next": null
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.items[]` | TxSummary | Transactions, newest first. |
| `data.next` | string \| null | Cursor for the next page; null on the last page. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `address`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Invalid DASH address.",
  "data": {
    "param": "address"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API409 (HTTP 409): Conflict

The history index is not built for that chain. Today only DASH has address history.

```json
{
  "status": 0,
  "code": "API409",
  "message": "Address history needs the history index, which is not built yet for this chain.",
  "data": {
    "reason": "history_unavailable"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Address history is available on DASH only today. BTC, LTC, BCH, ETH and TRON answer API409 `history_unavailable` until the history index is built.
- Check `features.addressHistory` in [Chains](https://docs.rarebl.com/api/stats/chains) before calling. Treat the `cursor` as opaque: pass `next` back unchanged.

---

# Address tokens

`GET https://api.rarebl.com/open/address/tokens` or `POST https://api.rarebl.com/open/address/tokens`

Token balances held by an ETH or TRON address: known tokens such as USDT and USDC, plus TRC-10 assets on TRON.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/address/tokens?chain=tron&address=TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. Tokens exist on eth and tron only. One of: eth, tron. |
| `address` | string | Yes | The ETH or TRON address. ETH: 0x + 40 hex. TRON: base58, starting with T. |

## Responses

### API200 (HTTP 200): OK

Token balances of a TRON address (shortened). TRC-10 assets have no symbol, name or decimals.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "tokens": [
      {
        "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "standard": "TRC-20",
        "symbol": "USDT",
        "name": "Tether USD",
        "decimals": 6,
        "balance": "0.00698"
      },
      {
        "contract": "1004989",
        "standard": "TRC-10",
        "symbol": null,
        "name": null,
        "decimals": null,
        "balance": "1111111"
      },
      {
        "contract": "1005119",
        "standard": "TRC-10",
        "symbol": null,
        "name": null,
        "decimals": null,
        "balance": "8888"
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.tokens[].contract` | string | Token contract address. |
| `data.tokens[].standard` | string | ERC-20, ERC-721, ERC-1155, TRC-20, TRC-721 or TRC-10. |
| `data.tokens[].symbol / name` | string \| null | Token symbol and name when known. |
| `data.tokens[].decimals` | integer \| null | Token decimals. |
| `data.tokens[].balance` | string | Balance as a decimal string in whole token units. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Tokens exist on eth and tron only.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Only known tokens are returned for now (for example USDT and USDC), not every token the address ever touched. On TRON, TRC-10 assets are listed too, with `symbol`, `name` and `decimals` null.
- An empty `tokens` array means none of the known tokens are held.

---

# Token

`GET https://api.rarebl.com/open/token/info` or `POST https://api.rarebl.com/open/token/info`

Metadata of a token contract on ETH or TRON: standard, name, symbol, decimals and total supply.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/token/info?chain=tron&contract=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. Tokens exist on eth and tron only. One of: eth, tron. |
| `contract` | string | Yes | The token contract address. ETH: 0x + 40 hex. TRON: base58, starting with T. |

## Responses

### API200 (HTTP 200): OK

Metadata of the TRC-20 USDT contract on TRON (`details` shortened).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "token": {
      "chain": "tron",
      "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "standard": "TRC-20",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "totalSupply": "94207597532.054777",
      "holders": null,
      "transfers": null,
      "details": [
        {
          "key": "standard",
          "label": "Standard",
          "value": "TRC-20",
          "kind": "text"
        },
        {
          "key": "contract",
          "label": "Contract",
          "value": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
          "kind": "address"
        },
        {
          "key": "decimals",
          "label": "Decimals",
          "value": 6,
          "kind": "number"
        }
      ]
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.token.standard` | string | ERC-20, ERC-721, ERC-1155, TRC-20, TRC-721 or TRC-10. |
| `data.token.name / symbol` | string \| null | Token name and symbol. |
| `data.token.decimals` | integer \| null | Token decimals. |
| `data.token.totalSupply` | string \| null | Total supply in whole token units. |
| `data.token.holders / transfers` | integer \| null | Null until the history index exists. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Tokens exist on eth and tron only.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The token does not exist on that chain.

```json
{
  "status": 0,
  "code": "API404",
  "message": "No contract at this address.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- `holders` and `transfers` are null today: they need the history index.

---

# Recommended fees

`GET https://api.rarebl.com/open/fees/recommended` or `POST https://api.rarebl.com/open/fees/recommended`

Recommended fees for every chain at three speeds — fastest, medium and normal: the miner fee on BTC, LTC, BCH and DASH (sat/vB), the gas price on ETH (Gwei) and the energy price on TRON (sun).

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/fees/recommended?chain=btc"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to query. One of: btc, ltc, bch, dash, eth, tron. |

## Responses

### API200 (HTTP 200): OK

Bitcoin fees from the node estimator.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "fees": {
      "chain": "btc",
      "unit": "sat/vB",
      "slow": "0.12",
      "standard": "0.13",
      "fast": "1",
      "baseFee": null,
      "details": [
        {
          "key": "source",
          "label": "Source",
          "value": "Node fee estimator (estimatesmartfee)",
          "kind": "text"
        },
        {
          "key": "slow",
          "label": "Slow target",
          "value": "24 blocks",
          "kind": "text"
        },
        {
          "key": "standard",
          "label": "Standard target",
          "value": "6 blocks",
          "kind": "text"
        },
        {
          "key": "fast",
          "label": "Fast target",
          "value": "2 blocks",
          "kind": "text"
        },
        {
          "key": "mempoolMinFee",
          "label": "Mempool minimum fee",
          "value": "0.1",
          "kind": "number",
          "unit": "sat/vB"
        }
      ],
      "updatedAt": "2026-11-14T22:39:36Z"
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.fees.unit` | string | `sat/vB` (UTXO), `Gwei` (ETH) or `sun` (TRON). |
| `data.fees.fast` | string \| null | Fastest: aims for the next block or two (UTXO estimator target 2 blocks), in `unit`. |
| `data.fees.standard` | string \| null | Medium: about 6 blocks on UTXO chains (about an hour on BTC). On TRON this is the energy price. |
| `data.fees.slow` | string \| null | Normal: the cheapest sensible rate, about 24 blocks on UTXO chains. |
| `data.fees.baseFee` | string \| null | ETH base fee in Gwei; null elsewhere. |
| `data.fees.details` | DetailRow[] | Estimator targets, TRON energy and bandwidth prices, ETH priority fee percentiles. |
| `data.fees.updatedAt` | string | When the value was computed (ISO 8601 UTC). |

### API200 (HTTP 200): OK (TRON)

TRON: `standard` is the energy price in sun per energy unit; `slow` and `fast` are null.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "fees": {
      "chain": "tron",
      "unit": "sun",
      "slow": null,
      "standard": "100",
      "fast": null,
      "baseFee": null,
      "details": [
        {
          "key": "energyPrice",
          "label": "Energy price",
          "value": "100",
          "kind": "number",
          "unit": "sun",
          "hint": "Cost of one unit of energy when burning TRX (1 TRX = 1,000,000 sun)."
        },
        {
          "key": "bandwidthPrice",
          "label": "Bandwidth price",
          "value": "1000",
          "kind": "number",
          "unit": "sun",
          "hint": "Cost of one byte of bandwidth when burning TRX."
        },
        {
          "key": "newAccountFee",
          "label": "Account activation fee",
          "value": "1",
          "kind": "amount",
          "unit": "TRX"
        }
      ],
      "updatedAt": "2026-11-14T22:39:44Z"
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Unknown or missing chain.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Speeds: `fast` = fastest, `standard` = medium, `slow` = normal. Pass the same names as `priority` to [Build a transaction](https://docs.rarebl.com/api/tx/build), or a value from here as `feeRate`.
- UTXO miner fees are in sat/vB on all four chains. Bitcoin Cash has no estimator on the node: all three values are the relay minimum.
- The older path `/open/gas/oracle` returns the same reply.
- On TRON `standard` is the energy price in sun per energy unit, and `slow` and `fast` are null. 1 TRX = 1,000,000 sun.
- Fees are cached for 5 to 15 seconds. To read the standard fee of every chain in one call, use [Live stats](https://docs.rarebl.com/api/stats/live).

---

# Search

`GET https://api.rarebl.com/open/search/query` or `POST https://api.rarebl.com/open/search/query`

Find out what a pasted string is: a block height, a transaction or block hash, an address in any format, a token name or a contract, or a link from another explorer. Every plausible match comes back ranked, with a confidence and a reason.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v1.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/search/query?q=800000&limit=20"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | Yes | The text to look up: a block height, a transaction or block hash (with or without `0x`), an address (BTC, LTC, BCH, DASH, ETH, TRON), a token symbol, name or contract, a link from another explorer (mempool.space, etherscan, tronscan, blockchair) or a `bitcoin:` or `ethereum:` payment link. Whitespace and quotes are removed. Not empty; at most 256 characters. |
| `mode` | string | No | full (default) checks heights and hashes against the nodes of every candidate chain. fast makes no node call: addresses and names are answered from checksums and the token list, heights and hashes come back with `verified: false`. Use fast for as-you-type suggestions. Default full. One of: full, fast. |
| `chain` | string | No | Only return matches on this chain (and ask only its node). One of: btc, ltc, bch, dash, eth, tron. |
| `limit` | integer | No | The most results to return. 1 to 20. Default 20. Default 20. |

## Responses

### API200 (HTTP 200): OK

Every match, ranked, with a label ready to display. A block height exists on several chains, so there are several results and `ambiguous` is true.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "results": [
      {
        "chain": "btc",
        "type": "block",
        "id": "800000",
        "label": "Block 800000 · Bitcoin",
        "confidence": 0.7,
        "reason": "Block 800000 exists on Bitcoin",
        "verified": true,
        "path": "/btc/block/800000",
        "rank": 1
      },
      {
        "chain": "ltc",
        "type": "block",
        "id": "800000",
        "label": "Block 800000 · Litecoin",
        "confidence": 0.7,
        "reason": "Block 800000 exists on Litecoin",
        "verified": true,
        "path": "/ltc/block/800000",
        "rank": 2
      },
      {
        "chain": "bch",
        "type": "block",
        "id": "800000",
        "label": "Block 800000 · Bitcoin Cash",
        "confidence": 0.7,
        "reason": "Block 800000 exists on Bitcoin Cash",
        "verified": true,
        "path": "/bch/block/800000",
        "rank": 3
      },
      {
        "chain": "dash",
        "type": "block",
        "id": "800000",
        "label": "Block 800000 · Dash",
        "confidence": 0.7,
        "reason": "Block 800000 exists on Dash",
        "verified": true,
        "path": "/dash/block/800000",
        "rank": 4
      }
    ],
    "best": {
      "chain": "btc",
      "type": "block",
      "id": "800000",
      "label": "Block 800000 · Bitcoin",
      "confidence": 0.7,
      "reason": "Block 800000 exists on Bitcoin",
      "verified": true,
      "path": "/btc/block/800000",
      "rank": 1
    },
    "ambiguous": true,
    "query": {
      "input": "800000",
      "normalized": "800000",
      "kind": "height",
      "source": "plain",
      "chain": null,
      "type": null,
      "payment": null
    },
    "suggestions": [],
    "unavailable": [],
    "mode": "full"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.results[].chain` | string | Chain id. |
| `data.results[].type` | string | `block`, `tx`, `address`, `token`, `contract` (an Ethereum address with code that is not a token) or `chain` (the query was a chain name such as `bitcoin`). |
| `data.results[].id` | string | The id to pass to the matching endpoint (ETH block and tx ids carry 0x; BCH addresses are CashAddr without prefix; for `chain` it is the chain id). |
| `data.results[].label` | string | A display label. |
| `data.results[].confidence` | number | How likely this is what was meant, 0 to 1. Results are sorted by it. |
| `data.results[].reason` | string | Why it matched, in words. |
| `data.results[].verified` | boolean | True when a node or a checksum confirmed it; false in `fast` mode for heights and hashes. |
| `data.results[].path` | string | The path of the matching page on explorer.rarebl.com. |
| `data.results[].rank` | integer | 1 for the most likely result. |
| `data.results[].token` | object | For tokens: `symbol`, `name`, `standard` and `decimals`. |
| `data.best` | object \| null | The first result, or null when nothing matched. |
| `data.ambiguous` | boolean | True when the second result is nearly as likely as the first (a height on several chains, the same token on two chains). When false you can open `best` at once. |
| `data.query.normalized` | string \| null | The identifier found in what was sent, after removing noise, link and payment-URI wrappers. |
| `data.query.kind` | string | `height`, `hash`, `eth-address`, `tron-address`, `utxo-address`, `name`, `secret` or `none`. |
| `data.query.source` | string | `plain`, `uri:<scheme>` or `url:<host>`. |
| `data.query.chain` | string \| null | The chain named by a link or payment URI. |
| `data.query.payment` | object \| null | Amount, label, message or recipient of a payment link. Not used for the search. |
| `data.suggestions[].kind` | string | `invalid_checksum`, `wrong_length`, `wrong_characters`, `incomplete`, `testnet`, `unsupported_format`, `not_found`, `unavailable`, `secret`, `note` or `hint`. Branch on this, not on the message. |
| `data.suggestions[].message` | string | What was wrong or worth knowing, for display. |
| `data.unavailable[]` | string[] | Chains whose node did not answer inside the time budget; their matches may be missing. |
| `data.mode` | string | The mode used: `full` or `fast`. |

### API400 (HTTP 400): Bad Request

The `q` parameter is missing or longer than 256 characters, or `mode`, `chain` is not one of its values. `data.param` names it.

```json
{
  "status": 0,
  "code": "API400",
  "message": "Missing parameter: q.",
  "data": {
    "param": "q"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (5 requests per second per IP, burst 20). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Digits (at most 10), also written `#975,838` or `block 975838`: a block height on every chain where that height exists.
- 64 hex characters, with or without `0x`, any case: a transaction or block hash. With `0x` Ethereum is asked first and the other chains only if it misses; without it every chain is asked at once, in parallel. A hash shared by Bitcoin and Bitcoin Cash (old history) returns both, Bitcoin first.
- `0x` + 40 hex: an Ethereum address. Mixed case must match its EIP-55 checksum, otherwise there is no result and an `invalid_checksum` suggestion. `type` is `token` for a known token or a contract that answers `symbol()`, `contract` for other code, `address` otherwise. `T` + 33 base58, or the 41-prefixed hex form: a TRON address or TRC-20 contract.
- Bitcoin: base58 `1…` and `3…`, bech32 `bc1q…` and bech32m `bc1p…` (all lower or all upper case). Litecoin: `L…`, `M…`, `ltc1…`. Dash: `X…`, `7…`. Bitcoin Cash: CashAddr `q…`, `p…` with or without `bitcoincash:`, in one case. A legacy `1…` or `3…` string is also valid on Bitcoin Cash (and `3…` on Litecoin), so those are returned too, ranked far lower: `ambiguous` stays false.
- Token names and symbols (`USDT`, `tether`, `usd coin`), chain names (`bitcoin`, `ltc`) and the start of a contract address (`0xdac17f`, at least 5 hex characters) match by exact, prefix and word, and tolerate a typo.
- Links from mempool.space, blockstream, blockchair, blockcypher, cryptoid, etherscan, tronscan and explorer.rarebl.com, and `bitcoin:`, `litecoin:`, `bitcoincash:`, `dash:` and `ethereum:` payment links, are reduced to the identifier inside; the chain and kind named by the link re-rank the matches. A link for another network (BNB Chain, Polygon, a test network) is read but its matches are marked down and annotated in `suggestions`.
- Private keys (WIF), `xprv` and `xpub` keys are never searched or echoed: `query.input` is null and `suggestions` holds a `secret` or `unsupported_format` entry.
- No result is an empty `results` array with `API200`, not an error: read `suggestions` for the reason. Answers are cached for 30 seconds, a miss for 12. See the guide [Look up any address or hash](https://docs.rarebl.com/guides/look-up-anything).

---

# Build a transaction

`POST https://api.rarebl.com/open/tx/build`

Builds an unsigned transaction on any chain and returns the digests to sign. The API supplies UTXOs or nonce and fees; your keys never leave you.

**Rate class:** compute (2 requests per second, burst 10, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/tx/build" -H "Content-Type: application/json" -d '{"chain":"dash","from":"[\"XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF\"]","to":"[{\"address\":\"XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM\",\"amount\":\"0.01\"}]","priority":"standard"}'`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to build for. One of: btc, ltc, bch, dash, eth, tron. |
| `from` | array \| string | No | UTXO chains: an array of addresses we may spend from (watched on BTC/LTC/BCH, any on DASH). ETH and TRON: the sender address (one address). Use `from` or `inputs` on UTXO chains. |
| `inputs` | array | No | UTXO chains: exact inputs `[{"txid","vout"}]`, verified unspent with `gettxout`. Any UTXO chain. At most 10 inputs on the hosted endpoints. |
| `to` | array \| string | Yes | UTXO chains: recipients `[{"address","amount"}]` (one entry only). ETH and TRON: the recipient address (one recipient). `amount: "max"` sends everything less the fee. |
| `amount` | string | No | ETH and TRON: the amount in whole units (or `"max"`), as the SDKs send it. UTXO chains put the amount inside each `to` entry. |
| `change` | string | No | UTXO change address. Default: the first `from` address. |
| `feeRate` | string | No | Fee rate in sat/vB (UTXO). Use `feeRate` or `priority`. |
| `priority` | string | No | Fee choice instead of `feeRate`. One of: slow, standard, fast. |
| `rbf` | boolean | No | Signal replace-by-fee (BTC and LTC). Default true. One of: true, false. |
| `opReturn` | string | No | Optional OP_RETURN payload as hex. At most 80 bytes; UTXO chains. |
| `token` | string | No | ERC-20 (ETH) or TRC-20 (TRON) contract address for a token transfer. |
| `gasLimit` | string | No | ETH: gas limit. |
| `maxFeePerGas` | string | No | ETH: max fee per gas, Gwei. |
| `maxPriorityFeePerGas` | string | No | ETH: max priority fee per gas, Gwei. |
| `feeLimit` | integer | No | TRON: fee limit in sun. |

## Responses

### API200 (HTTP 200): OK

A Dash transaction built from one input: a real reply (nothing was signed or broadcast).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "unsigned": {
      "chain": "dash",
      "format": "utxo-v1",
      "tx": "0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a0100000000ffffffff0240420f00000000001976a91454072845a9ca039a5b585f5fd994d88d38feb31c88ac189f3419000000001976a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac00000000",
      "inputs": [
        {
          "txid": "7a08e8423f8f4bfe21b0569547b6315f16a94b42d72be5d972a86e0385619f13",
          "vout": 1,
          "address": "XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF",
          "value": "4.23879226",
          "valueSats": "423879226",
          "scriptPubKey": "76a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac",
          "scriptType": "p2pkh",
          "sequence": 4294967295
        }
      ],
      "outputs": [
        {
          "address": "XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM",
          "value": "0.01",
          "valueSats": "1000000",
          "change": false
        },
        {
          "address": "XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF",
          "value": "4.22879",
          "valueSats": "422879000",
          "change": true
        }
      ],
      "fee": "0.00000226",
      "feeSats": "226",
      "vsize": 226,
      "feeRate": "1"
    },
    "toSign": [
      {
        "index": 0,
        "address": "XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF",
        "digest": "60f09e680a8d4d7442ec09e2e89181c568f596c6200c6a2d2f4aa15a4a8fc6b1",
        "algorithm": "ecdsa-secp256k1",
        "sighashType": 1,
        "scriptType": "p2pkh"
      }
    ],
    "expiresAt": "2026-11-15T00:31:27Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.unsigned` | object | The unsigned transaction. `format` is `utxo-v1`, `eth-1559-v1` or `tron-v1`. UTXO: `tx`, `psbt` (BTC/LTC), `inputs[]` (each legacy p2pkh input on BTC, LTC and DASH also carries `prevTx`, the raw previous transaction as hex), `outputs[]`, `fee`, `feeSats`, `vsize`, `feeRate`. |
| `data.toSign[]` | object[] | `{index, address, digest, algorithm, sighashType?, scriptType?}`: the 32-byte hex digests to sign. |
| `data.expiresAt` | string | ISO 8601. TRON expiration; for UTXO and ETH advisory (fees, nonce). |

### API200 (HTTP 200): OK (ETH token)

An ERC-20 (USDT) transfer on Ethereum (sample values): `unsigned.tx` carries the EIP-1559 fields, the digest is the keccak256 of the typed payload.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "unsigned": {
      "chain": "eth",
      "format": "eth-1559-v1",
      "tx": {
        "from": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
        "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "nonce": 42,
        "gasLimit": "65000",
        "maxFeePerGas": "18.5",
        "maxPriorityFeePerGas": "1.2",
        "value": "0",
        "data": "0xa9059cbb000000000000000000000000dead00000000000000000000000000000000dead00000000000000000000000000000000000000000000000000000000017d7840",
        "chainId": 1
      }
    },
    "toSign": [
      {
        "index": 0,
        "address": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
        "digest": "9b2c4f0a6d81e3375a40c1be52d9f8a7140c6e3bd52a97f08e1c4d63b0a5f287",
        "algorithm": "ecdsa-secp256k1-recoverable"
      }
    ],
    "expiresAt": "2026-11-15T00:50:00Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Unknown or missing chain.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API409 (HTTP 409): Conflict

BTC, LTC or BCH: a `from` address is not watched and active yet. Start a watch with [address/watch](https://docs.rarebl.com/api/address/watch).

```json
{
  "status": 0,
  "code": "API409",
  "message": "This address is not watched yet.",
  "data": {
    "reason": "not_watched"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

The selected inputs cannot pay the outputs plus the fee.

```json
{
  "status": 0,
  "code": "API422",
  "message": "The inputs do not cover the amount and the fee.",
  "data": {
    "reason": "insufficient_funds"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

An output (often the change) is too small to be relayed.

```json
{
  "status": 0,
  "code": "API422",
  "message": "An output is below the dust limit.",
  "data": {
    "reason": "dust_output"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (compute class: 2 requests per second, burst 10, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Three ways to send: [sign locally with the SDK](https://docs.rarebl.com/guides/sign-locally) (recommended), [sign the digests yourself](https://docs.rarebl.com/guides/send-a-transaction), or [hosted signing](https://docs.rarebl.com/guides/hosted-signing). See [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).
- The digest depends on the script type: legacy sighash for p2pkh, BIP143 for p2wpkh and p2sh-p2wpkh, BIP341 for p2tr key path (Schnorr), BIP143-style with FORKID (`0x41`) for BCH, keccak256 of the EIP-1559 payload for ETH and sha256 of `raw_data` for TRON. ECDSA signatures are RFC 6979 and low-S.
- ETH and TRON take `from` (one address), `to` (one recipient) and optionally `token`. ETH also takes `gasLimit`, `maxFeePerGas` and `maxPriorityFeePerGas`; TRON takes `feeLimit` (sun).
- Legacy p2pkh inputs (BTC, LTC, DASH) carry `prevTx` in `unsigned.inputs[]`. A legacy signature does not commit to the input amount, so the SDKs check that `prevTx` hashes to the input's `txid` and read the amount from it before signing.
- The [SDKs](https://docs.rarebl.com/sdks/js) build, verify and sign locally, so you rarely call this endpoint by hand. See [Send a transaction](https://docs.rarebl.com/guides/send-a-transaction).
- The ETH example shows the shape; its hex strings and digest are sample values.

---

# Assemble a signed transaction

`POST https://api.rarebl.com/open/tx/assemble`

Inserts your signatures into an unsigned transaction from tx/build, verifies them, and can broadcast the result in the same call.

**Rate class:** compute (2 requests per second, burst 10, per IP). **Available since:** Open API v2.

**Warning.** With broadcast set to true this really broadcasts the transaction to the live network. It cannot be undone.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/tx/assemble" -H "Content-Type: application/json" -d '{"unsigned":{"chain":"dash","format":"utxo-v1","tx":"0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a0100000000ffffffff0240420f00000000001976a91454072845a9ca039a5b585f5fd994d88d38feb31c88ac189f3419000000001976a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac00000000","inputs":[{"txid":"7a08e8423f8f4bfe21b0569547b6315f16a94b42d72be5d972a86e0385619f13","vout":1,"address":"XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF","value":"4.23879226","valueSats":"423879226","scriptPubKey":"76a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac","scriptType":"p2pkh","sequence":4294967295}],"outputs":[{"address":"XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM","value":"0.01","valueSats":"1000000","change":false},{"address":"XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF","value":"4.22879","valueSats":"422879000","change":true}],"fee":"0.00000226","feeSats":"226","vsize":226,"feeRate":"1"},"signatures":[{"index":0,"signature":"3044022047ac8e878352d3ebbde1c94ce3a10d057c24175747116f8288e5d794d12d482f0220217f36a485cae903c713331d877c1f64677e3622ad4010726870540656fe9dcb01","publicKey":"03ad1d8e89212f0b92c74d23bb710c00662ad1470198ac48c43f7d6f93a2a26873"}],"broadcast":false}'`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `unsigned` | object | Yes | The `unsigned` object exactly as returned by tx/build. |
| `signatures` | array | Yes | One entry per digest: `{index, signature, publicKey}`. UTXO: DER plus the sighash byte (ECDSA) or 64/65-byte hex (Schnorr); `publicKey` is the 33-byte compressed key (p2tr: 32-byte x-only). ETH and TRON: 65-byte `r‖s‖v` hex (v = 0/1 or 27/28), `publicKey` optional. |
| `broadcast` | boolean | No | Broadcast the signed transaction. With `true` the call is in the write class and really broadcasts. Default false. One of: false, true. |

## Responses

### API200 (HTTP 200): OK

A signed transaction, not broadcast.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "signed": {
      "chain": "dash",
      "hex": "0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a010000006a473044022047ac8e878352d3ebbde1c94ce3a10d057c24175747116f8288e5d794d12d482f0220217f36a485cae903c713331d877c1f64677e3622ad4010726870540656fe9dcb012103ad1d8e89212f0b92c74d23bb710c00662ad1470198ac48c43f7d6f93a2a26873ffffffff0240420f00000000001976a91454072845a9ca039a5b585f5fd994d88d38feb31c88ac189f3419000000001976a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac00000000",
      "txid": "8235cfafa0ef70d4a5135331c6889a7c15780b7aeb3bc20721571c2a4b51ffa7"
    },
    "broadcast": null
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.signed` | object | `{chain, hex \| tx, txid}`: the signed transaction (UTXO and ETH `hex`, TRON `tx`). |
| `data.broadcast` | object \| null | null unless `broadcast: true`; then `{txid, accepted, alreadyKnown}`. |

### API200 (HTTP 200): OK (broadcast)

With `broadcast: true`.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "signed": {
      "chain": "dash",
      "hex": "0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a010000006a473044022047ac8e878352d3ebbde1c94ce3a10d057c24175747116f8288e5d794d12d482f0220217f36a485cae903c713331d877c1f64677e3622ad4010726870540656fe9dcb012103ad1d8e89212f0b92c74d23bb710c00662ad1470198ac48c43f7d6f93a2a26873ffffffff0240420f00000000001976a91454072845a9ca039a5b585f5fd994d88d38feb31c88ac189f3419000000001976a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac00000000",
      "txid": "8235cfafa0ef70d4a5135331c6889a7c15780b7aeb3bc20721571c2a4b51ffa7"
    },
    "broadcast": {
      "txid": "8235cfafa0ef70d4a5135331c6889a7c15780b7aeb3bc20721571c2a4b51ffa7",
      "accepted": true,
      "alreadyKnown": false
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

We verify every signature against its digest and public key.

```json
{
  "status": 0,
  "code": "API422",
  "message": "A signature does not verify against its digest.",
  "data": {
    "reason": "bad_signature"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API403 (HTTP 403): Forbidden

The key must derive the address of the input it signs.

```json
{
  "status": 0,
  "code": "API403",
  "message": "The public key does not match the input address.",
  "data": {
    "reason": "key_mismatch"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

Only with `broadcast: true`: the node refused it. `data.detail` carries the node message.

```json
{
  "status": 0,
  "code": "API422",
  "message": "The node rejected the transaction.",
  "data": {
    "reason": "node_rejected",
    "detail": "min relay fee not met"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `unsigned`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "unsigned is required.",
  "data": {
    "param": "unsigned"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (compute class: 2 requests per second, burst 10, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- We check every signature against its digest and key, and that the key matches the input address (`bad_signature`, `key_mismatch`).
- Assemble without `broadcast` is in the compute class. With `broadcast: true` it is in the write class (6 per minute, burst 3, 300 per day).
- The SDK does build, verify, sign, assemble and broadcast in one `transfer()` call: see [Sign locally with the SDK](https://docs.rarebl.com/guides/sign-locally).

---

# Broadcast a transaction

`POST https://api.rarebl.com/open/tx/broadcast`

Sends a fully signed transaction to the network through Rarebl's own nodes, with pre-checks and an idempotency key.

**Rate class:** write (6 per minute, burst 3, 300 per day, per IP). **Available since:** Open API v2.

**Warning.** Try It! really broadcasts the transaction you paste here to the live network. It cannot be undone.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/tx/broadcast" -H "Content-Type: application/json" -H "Idempotency-Key: payout-2026-11-14-0001" -d '{"chain":"dash","hex":"0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a010000006a473044022047ac8e878352d3ebbde1c94ce3a10d057c24175747116f8288e5d794d12d482f0220217f36a485cae903c713331d877c1f64677e3622ad4010726870540656fe9dcb012103ad1d8e89212f0b92c74d23bb710c00662ad1470198ac48c43f7d6f93a2a26873ffffffff0240420f00000000001976a91454072845a9ca039a5b585f5fd994d88d38feb31c88ac189f3419000000001976a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac00000000"}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `Idempotency-Key` | No | Optional. The same key, or the same txid, within 24 hours returns the first result instead of broadcasting twice. Example: `payout-2026-11-14-0001`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain. One of: btc, ltc, bch, dash, eth, tron. |
| `hex` | string | No | The signed transaction hex (all chains; for TRON the signed protobuf hex). |
| `tx` | object | No | TRON only: the signed transaction JSON (use `tx` or `hex`). |
| `maxFeeRate` | string | No | UTXO: lowers the node's `maxfeerate` guard, in sat/vB. It can never raise it. |

## Responses

### API200 (HTTP 200): OK

Accepted by the node.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "txid": "8235cfafa0ef70d4a5135331c6889a7c15780b7aeb3bc20721571c2a4b51ffa7",
    "accepted": true,
    "alreadyKnown": false
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.txid` | string | The transaction id. |
| `data.accepted` | boolean | true when the node accepted it. |
| `data.alreadyKnown` | boolean | true when the node or an earlier idempotent call already had it. |

### API422 (HTTP 422): Unprocessable Entity

The node refused it. `data.detail` carries the node's message, for example `min relay fee not met`.

```json
{
  "status": 0,
  "code": "API422",
  "message": "The node rejected the transaction.",
  "data": {
    "reason": "node_rejected",
    "detail": "min relay fee not met"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

One of the inputs was spent by another transaction.

```json
{
  "status": 0,
  "code": "API422",
  "message": "An input is already spent.",
  "data": {
    "reason": "inputs_spent"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

ETH: the nonce must be at least the pending nonce.

```json
{
  "status": 0,
  "code": "API422",
  "message": "The nonce is lower than the pending nonce.",
  "data": {
    "reason": "nonce_too_low"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

ETH: the transaction is signed for another chain id.

```json
{
  "status": 0,
  "code": "API422",
  "message": "The chain id is not 1.",
  "data": {
    "reason": "chain_id_mismatch"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

TRON: the transaction expiration has passed.

```json
{
  "status": 0,
  "code": "API422",
  "message": "The transaction has expired.",
  "data": {
    "reason": "tx_expired"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

Size caps: 100 kB (UTXO), 128 kB (ETH), 64 kB (TRON).

```json
{
  "status": 0,
  "code": "API422",
  "message": "The transaction is too large.",
  "data": {
    "reason": "tx_too_large"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `hex`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "hex is required.",
  "data": {
    "param": "hex"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (write class: 6 per minute, burst 3, 300 per day, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Pre-checks: UTXO runs `testmempoolaccept` first, keeping the node's default `maxfeerate`. ETH requires chainId 1 and a nonce at least the pending nonce. TRON requires a signature and a transaction that has not expired.
- Size caps: 100 kB (UTXO), 128 kB (ETH), 64 kB (TRON).
- Write class: 6 per minute, burst 3, 300 per day, per IP. Use `Idempotency-Key` so a retry cannot broadcast twice.
- Rejections are `API422` with a `data.reason` (see [Responses & codes](https://docs.rarebl.com/responses-and-codes)) and, for `node_rejected`, a `data.detail`.

---

# Decode a transaction

`POST https://api.rarebl.com/open/tx/decode`

Decodes a raw transaction (signed or unsigned) into the v1 Tx shape, with status `unsent`, so you can check what you are about to send.

**Rate class:** compute (2 requests per second, burst 10, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/tx/decode" -H "Content-Type: application/json" -d '{"chain":"dash","hex":"0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a010000006a473044022047ac8e878352d3ebbde1c94ce3a10d057c24175747116f8288e5d794d12d482f0220217f36a485cae903c713331d877c1f64677e3622ad4010726870540656fe9dcb012103ad1d8e89212f0b92c74d23bb710c00662ad1470198ac48c43f7d6f93a2a26873ffffffff0240420f00000000001976a91454072845a9ca039a5b585f5fd994d88d38feb31c88ac189f3419000000001976a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac00000000"}'`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain. One of: btc, ltc, bch, dash, eth, tron. |
| `hex` | string | No | The raw transaction hex. |
| `tx` | object | No | TRON only: the transaction JSON (use `tx` or `hex`). |

## Responses

### API200 (HTTP 200): OK

The decoded transaction, with `status: "unsent"`.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "tx": {
      "chain": "dash",
      "hash": "8235cfafa0ef70d4a5135331c6889a7c15780b7aeb3bc20721571c2a4b51ffa7",
      "status": "unsent",
      "block": null,
      "blockHash": null,
      "time": null,
      "confirmations": 0,
      "value": "4.23879",
      "fee": "0.00000226",
      "utxo": {
        "size": 225,
        "vsize": 225,
        "weight": 900,
        "locktime": 0,
        "version": 2,
        "rbf": false,
        "coinbase": false,
        "inputs": [
          {
            "txid": "7a08e8423f8f4bfe21b0569547b6315f16a94b42d72be5d972a86e0385619f13",
            "vout": 1,
            "address": "XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF",
            "value": "4.23879226",
            "scriptType": "pubkeyhash",
            "sequence": 4294967295,
            "coinbase": false
          }
        ],
        "outputs": [
          {
            "n": 0,
            "address": "XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM",
            "value": "0.01",
            "scriptType": "pubkeyhash",
            "opReturn": null,
            "spent": null
          },
          {
            "n": 1,
            "address": "XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF",
            "value": "4.22879",
            "scriptType": "pubkeyhash",
            "opReturn": null,
            "spent": null
          }
        ]
      },
      "details": [
        {
          "key": "status",
          "label": "Status",
          "value": "Unsent",
          "kind": "text"
        }
      ]
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.tx` | Tx | The v1 [Tx](https://docs.rarebl.com/data-types) shape. Prevout values are filled where the node knows them. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `hex`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "hex is required.",
  "data": {
    "param": "hex"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (compute class: 2 requests per second, burst 10, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- The reply is the same `Tx` shape as [Transaction](https://docs.rarebl.com/api/tx/get), with `status: "unsent"`, no block and 0 confirmations.
- Use it to double-check outputs and fees before you broadcast.

---

# Estimate a transaction

`POST https://api.rarebl.com/open/tx/estimate`

Estimates the fee of a transaction without building digests. It takes the same body as tx/build.

**Rate class:** compute (2 requests per second, burst 10, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/tx/estimate" -H "Content-Type: application/json" -d '{"chain":"dash","from":"[\"XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF\"]","to":"[{\"address\":\"XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM\",\"amount\":\"0.01\"}]","priority":"standard"}'`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to build for. One of: btc, ltc, bch, dash, eth, tron. |
| `from` | array \| string | No | UTXO chains: an array of addresses we may spend from (watched on BTC/LTC/BCH, any on DASH). ETH and TRON: the sender address (one address). Use `from` or `inputs` on UTXO chains. |
| `inputs` | array | No | UTXO chains: exact inputs `[{"txid","vout"}]`, verified unspent with `gettxout`. Any UTXO chain. At most 10 inputs on the hosted endpoints. |
| `to` | array \| string | Yes | UTXO chains: recipients `[{"address","amount"}]` (one entry only). ETH and TRON: the recipient address (one recipient). `amount: "max"` sends everything less the fee. |
| `amount` | string | No | ETH and TRON: the amount in whole units (or `"max"`), as the SDKs send it. UTXO chains put the amount inside each `to` entry. |
| `change` | string | No | UTXO change address. Default: the first `from` address. |
| `feeRate` | string | No | Fee rate in sat/vB (UTXO). Use `feeRate` or `priority`. |
| `priority` | string | No | Fee choice instead of `feeRate`. One of: slow, standard, fast. |
| `rbf` | boolean | No | Signal replace-by-fee (BTC and LTC). Default true. One of: true, false. |
| `opReturn` | string | No | Optional OP_RETURN payload as hex. At most 80 bytes; UTXO chains. |
| `token` | string | No | ERC-20 (ETH) or TRC-20 (TRON) contract address for a token transfer. |
| `gasLimit` | string | No | ETH: gas limit. |
| `maxFeePerGas` | string | No | ETH: max fee per gas, Gwei. |
| `maxPriorityFeePerGas` | string | No | ETH: max priority fee per gas, Gwei. |
| `feeLimit` | integer | No | TRON: fee limit in sun. |

## Responses

### API200 (HTTP 200): OK

A Dash estimate.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "fee": "0.00000226",
    "feeSats": "226",
    "vsize": 226,
    "feeRate": "1"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.fee` | string | The fee in whole native units. |
| `data.feeSats` | string \| null | The fee in the integer base unit. |
| `data.vsize / feeRate` | number / string | UTXO: virtual size and the fee rate in sat/vB. |
| `data.gasLimit` | string | ETH only. |
| `data.energy / bandwidth` | number | TRON only. |

### API200 (HTTP 200): OK (TRON)

A TRON TRC-20 transfer estimate (energy and bandwidth).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "fee": "13.9",
    "feeSats": "13900000",
    "energy": 65000,
    "bandwidth": 345
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Unknown or missing chain.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API409 (HTTP 409): Conflict

BTC, LTC or BCH: a `from` address is not watched and active yet. Start a watch with [address/watch](https://docs.rarebl.com/api/address/watch).

```json
{
  "status": 0,
  "code": "API409",
  "message": "This address is not watched yet.",
  "data": {
    "reason": "not_watched"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

The selected inputs cannot pay the outputs plus the fee.

```json
{
  "status": 0,
  "code": "API422",
  "message": "The inputs do not cover the amount and the fee.",
  "data": {
    "reason": "insufficient_funds"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

An output (often the change) is too small to be relayed.

```json
{
  "status": 0,
  "code": "API422",
  "message": "An output is below the dust limit.",
  "data": {
    "reason": "dust_output"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (compute class: 2 requests per second, burst 10, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Same body as [Build a transaction](https://docs.rarebl.com/api/tx/build), without signing. Use it to show a fee before the user commits.
- For network-wide fee levels, use [Recommended fees](https://docs.rarebl.com/api/fees/recommended).

---

# Output spend status

`GET https://api.rarebl.com/open/tx/outspends`

For each output of a UTXO transaction, whether it is spent, by which transaction, and whether the spend is still in the mempool.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/tx/outspends?chain=btc&id=9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | A UTXO chain. One of: btc, ltc, bch, dash. |
| `id` | string | Yes | The transaction hash. 64 hex characters. |

## Responses

### API200 (HTTP 200): OK

Output 0 is unspent, output 1 is spent.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "outputs": [
      {
        "n": 0,
        "spent": false,
        "spentBy": null,
        "inMempool": false
      },
      {
        "n": 1,
        "spent": true,
        "spentBy": "15f0189bea2a90b1b7232e96e9d9728ac72187133ce2ad33f2ee464f45cb8fa8",
        "inMempool": false
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.outputs[]` | object[] | `{n, spent: true\|false\|null, spentBy: txid\|null, inMempool: bool}`. `spent` is null when it cannot be told. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `id`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Transaction id must be a 64-character hash.",
  "data": {
    "param": "id"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The transaction does not exist.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Transaction not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Check this before you spend an output, to be sure it is still unspent.
- UTXO chains only.

---

# Signer public key

`GET https://api.rarebl.com/open/tx/signer-key`

The X25519 public key you encrypt private keys to when you use hosted signing. Only the signer process can read what you encrypt to it.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/tx/signer-key"`

## Parameters

This endpoint takes no parameters.

## Responses

### API200 (HTTP 200): OK

The current signer key.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "kid": "k20261115-defd9c",
    "alg": "X25519",
    "publicKey": "wL-KbhcrI3WWpG1nv8sNAoiWUVTyw9yMxfn1_jvoxT4",
    "expiresAt": "2026-12-15T00:12:34.514Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.kid` | string | The key id. Put it in the envelope (`kid`). |
| `data.alg` | string | `X25519`. |
| `data.publicKey` | string | base64url, 32 bytes. |
| `data.expiresAt` | string | ISO 8601. Keys rotate; the previous `kid` stays valid for 7 days, and a key is refused 7 days after its `expiresAt`. |

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Only needed for [hosted signing](https://docs.rarebl.com/guides/hosted-signing). The SDKs fetch it and build the envelope for you: pass the whole `data` object (`{kid, publicKey}`) to `envelope.encrypt`.
- Keys rotate. The previous `kid` stays valid for 7 days after its successor was created, and the current key is refused 7 days after `expiresAt` (the reply is an error once it is overdue). Fetch a fresh key rather than hard-coding one, and fetch it again when tx/sign or tx/send answers `bad_envelope` or an unknown `kid`.
- Read class: 5 requests per second, burst 20.

---

# Sign a transaction (hosted)

`POST https://api.rarebl.com/open/tx/sign`

Sends private keys to Rarebl, which signs an unsigned transaction in memory and forgets the keys. It never broadcasts.

**Rate class:** write (6 per minute, burst 3, 300 per day, per IP). **Available since:** Open API v2.

**Try It is disabled for this endpoint.** A documentation page should never collect private keys, so Try It is off here. Use the snippets from your own server or an SDK.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/tx/sign" -H "Content-Type: application/json" -H "X-Rarebl-Accept-Risk: hosted-signing" -d '{"unsigned":{"chain":"dash","format":"utxo-v1","tx":"0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a0100000000ffffffff0240420f00000000001976a91454072845a9ca039a5b585f5fd994d88d38feb31c88ac189f3419000000001976a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac00000000","inputs":[{"txid":"7a08e8423f8f4bfe21b0569547b6315f16a94b42d72be5d972a86e0385619f13","vout":1,"address":"XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF","value":"4.23879226","valueSats":"423879226","scriptPubKey":"76a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac","scriptType":"p2pkh","sequence":4294967295}],"outputs":[{"address":"XiM9Afap6UEb5LDkcWrg2YyA28hifkZZKM","value":"0.01","valueSats":"1000000","change":false},{"address":"XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF","value":"4.22879","valueSats":"422879000","change":true}],"fee":"0.00000226","feeSats":"226","vsize":226,"feeRate":"1"},"keys":{"encrypted":"BASE64URL_ENVELOPE_FROM_SDK"}}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Rarebl-Accept-Risk` | Yes | Required acknowledgement that you are sending private keys to a hosted signer. The only accepted value is `hosted-signing`; without it the API answers `API403` `risk_not_acknowledged`. Example: `hosted-signing`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `unsigned` | object | Yes | The `unsigned` object from tx/build. |
| `keys` | object | Yes | The private keys. `{"encrypted": "<envelope>"}`: an envelope v2 encrypted to the signer key from [tx/signer-key](https://docs.rarebl.com/api/tx/signer-key), bound to the chain, the operation (`sign` for tx/sign, `send` for tx/send) and the digests or recipients it names, valid for at most 300 seconds and single-use. Also accepted: `{"privateKeys": ["<WIF or 64-hex>"]}`, which carries no binding. See [Hosted signing](https://docs.rarebl.com/guides/hosted-signing). |

## Responses

### API200 (HTTP 200): OK

The signed transaction, not broadcast.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "signed": {
      "chain": "dash",
      "hex": "0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a010000006a473044022047ac8e878352d3ebbde1c94ce3a10d057c24175747116f8288e5d794d12d482f0220217f36a485cae903c713331d877c1f64677e3622ad4010726870540656fe9dcb012103ad1d8e89212f0b92c74d23bb710c00662ad1470198ac48c43f7d6f93a2a26873ffffffff0240420f00000000001976a91454072845a9ca039a5b585f5fd994d88d38feb31c88ac189f3419000000001976a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac00000000",
      "txid": "8235cfafa0ef70d4a5135331c6889a7c15780b7aeb3bc20721571c2a4b51ffa7"
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API403 (HTTP 403): Forbidden

The header `X-Rarebl-Accept-Risk: hosted-signing` is missing.

```json
{
  "status": 0,
  "code": "API403",
  "message": "Hosted signing needs the risk acknowledgement header.",
  "data": {
    "reason": "risk_not_acknowledged"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API403 (HTTP 403): Forbidden

Every key must derive the address of an input it signs. Unused keys are refused.

```json
{
  "status": 0,
  "code": "API403",
  "message": "A key does not match the input addresses.",
  "data": {
    "reason": "key_mismatch"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API403 (HTTP 403): Forbidden

The envelope (`op: "sign"`) must list exactly the `toSign` digests that the signer recomputes from `unsigned`; an extra, missing or different digest is refused and nothing is signed.

```json
{
  "status": 0,
  "code": "API403",
  "message": "The digests are not the ones the envelope names.",
  "data": {
    "reason": "digest_not_bound"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

The envelope is unreadable, is a v1 envelope, names an unknown `kid`, has an `op` that does not match the route, or has an `exp` more than 300 seconds ahead. Fetch [tx/signer-key](https://docs.rarebl.com/api/tx/signer-key) again and encrypt again with SDK 0.2.0 or later.

```json
{
  "status": 0,
  "code": "API400",
  "message": "The envelope could not be read.",
  "data": {
    "reason": "bad_envelope"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

The envelope's `exp` has passed. Make a new envelope right before the request.

```json
{
  "status": 0,
  "code": "API400",
  "message": "The envelope has expired.",
  "data": {
    "reason": "envelope_expired"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API409 (HTTP 409): Conflict

An envelope opens once. Make a new envelope for every request, including a retry.

```json
{
  "status": 0,
  "code": "API409",
  "message": "The envelope was already used.",
  "data": {
    "reason": "envelope_replayed"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

The `chain` in the envelope is not the chain of the request.

```json
{
  "status": 0,
  "code": "API400",
  "message": "The envelope is for another chain.",
  "data": {
    "reason": "chain_mismatch"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A key-like value was found in the query string. The request is dropped unprocessed.

```json
{
  "status": 0,
  "code": "API400",
  "message": "Keys must be sent in the request body.",
  "data": {
    "reason": "plaintext_key_in_query"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

The signer could not produce a valid signature.

```json
{
  "status": 0,
  "code": "API422",
  "message": "Signing failed.",
  "data": {
    "reason": "bad_signature"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (write class: 6 per minute, burst 3, 300 per day, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Walkthrough: [Hosted signing](https://docs.rarebl.com/guides/hosted-signing). To keep keys on your side, [sign locally](https://docs.rarebl.com/guides/sign-locally) instead.
- Keys go in a POST body only, and the header `X-Rarebl-Accept-Risk: hosted-signing` is mandatory. An envelope v2 with `op: "sign"` and the `digests` of the build is bound to what it names; a plain `privateKeys` body is accepted but carries no binding.
- Every key must derive the address of an input it signs, at most 10 inputs per request. Keys are used in memory by a separate signer process and wiped after use; request bodies on this path are excluded from all logging. Replies are `Cache-Control: no-store`.
- Write class: 6 per minute, burst 3, 300 per day per IP.

---

# Build, sign and send (hosted)

`POST https://api.rarebl.com/open/tx/send`

One call that builds, signs with the keys you send, and broadcasts.

**Rate class:** write (6 per minute, burst 3, 300 per day, per IP). **Available since:** Open API v2.

**Try It is disabled for this endpoint.** A documentation page should never collect private keys, so Try It is off here. Use the snippets from your own server or an SDK.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/tx/send" -H "Content-Type: application/json" -H "X-Rarebl-Accept-Risk: hosted-signing" -H "Idempotency-Key: payout-2026-11-14-0002" -d '{"chain":"btc","from":"[\"bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q\"]","to":"[{\"address\":\"bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm\",\"amount\":\"0.0015\"}]","priority":"standard","keys":{"encrypted":"BASE64URL_ENVELOPE_FROM_SDK"}}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Rarebl-Accept-Risk` | Yes | Required acknowledgement that you are sending private keys to a hosted signer. The only accepted value is `hosted-signing`; without it the API answers `API403` `risk_not_acknowledged`. Example: `hosted-signing`. |
| `Idempotency-Key` | No | Optional, as on tx/broadcast. Example: `payout-2026-11-14-0002`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain to build for. One of: btc, ltc, bch, dash, eth, tron. |
| `from` | array \| string | No | UTXO chains: an array of addresses we may spend from (watched on BTC/LTC/BCH, any on DASH). ETH and TRON: the sender address (one address). Use `from` or `inputs` on UTXO chains. |
| `inputs` | array | No | UTXO chains: exact inputs `[{"txid","vout"}]`, verified unspent with `gettxout`. Any UTXO chain. At most 10 inputs on the hosted endpoints. |
| `to` | array \| string | Yes | UTXO chains: recipients `[{"address","amount"}]` (one entry only). ETH and TRON: the recipient address (one recipient). `amount: "max"` sends everything less the fee. |
| `amount` | string | No | ETH and TRON: the amount in whole units (or `"max"`), as the SDKs send it. UTXO chains put the amount inside each `to` entry. |
| `change` | string | No | UTXO change address. Default: the first `from` address. |
| `feeRate` | string | No | Fee rate in sat/vB (UTXO). Use `feeRate` or `priority`. |
| `priority` | string | No | Fee choice instead of `feeRate`. One of: slow, standard, fast. |
| `rbf` | boolean | No | Signal replace-by-fee (BTC and LTC). Default true. One of: true, false. |
| `opReturn` | string | No | Optional OP_RETURN payload as hex. At most 80 bytes; UTXO chains. |
| `token` | string | No | ERC-20 (ETH) or TRC-20 (TRON) contract address for a token transfer. |
| `gasLimit` | string | No | ETH: gas limit. |
| `maxFeePerGas` | string | No | ETH: max fee per gas, Gwei. |
| `maxPriorityFeePerGas` | string | No | ETH: max priority fee per gas, Gwei. |
| `feeLimit` | integer | No | TRON: fee limit in sun. |
| `keys` | object | Yes | The private keys. `{"encrypted": "<envelope>"}`: an envelope v2 encrypted to the signer key from [tx/signer-key](https://docs.rarebl.com/api/tx/signer-key), bound to the chain, the operation (`sign` for tx/sign, `send` for tx/send) and the digests or recipients it names, valid for at most 300 seconds and single-use. Also accepted: `{"privateKeys": ["<WIF or 64-hex>"]}`, which carries no binding. See [Hosted signing](https://docs.rarebl.com/guides/hosted-signing). |

## Responses

### API200 (HTTP 200): OK

Built, signed and broadcast.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "signed": {
      "chain": "dash",
      "hex": "0200000001139f6185036ea872d9e52bd7424ba9165f31b6479556b021fe4b8f3f42e8087a010000006a473044022047ac8e878352d3ebbde1c94ce3a10d057c24175747116f8288e5d794d12d482f0220217f36a485cae903c713331d877c1f64677e3622ad4010726870540656fe9dcb012103ad1d8e89212f0b92c74d23bb710c00662ad1470198ac48c43f7d6f93a2a26873ffffffff0240420f00000000001976a91454072845a9ca039a5b585f5fd994d88d38feb31c88ac189f3419000000001976a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac00000000",
      "txid": "8235cfafa0ef70d4a5135331c6889a7c15780b7aeb3bc20721571c2a4b51ffa7"
    },
    "broadcast": {
      "txid": "8235cfafa0ef70d4a5135331c6889a7c15780b7aeb3bc20721571c2a4b51ffa7",
      "accepted": true,
      "alreadyKnown": false
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.signed` | object | `{chain, hex \| tx, txid}`. |
| `data.broadcast` | object | `{txid, accepted, alreadyKnown}`. |

### API403 (HTTP 403): Forbidden

The header `X-Rarebl-Accept-Risk: hosted-signing` is missing.

```json
{
  "status": 0,
  "code": "API403",
  "message": "Hosted signing needs the risk acknowledgement header.",
  "data": {
    "reason": "risk_not_acknowledged"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API403 (HTTP 403): Forbidden

Every key must derive the address of an input it signs.

```json
{
  "status": 0,
  "code": "API403",
  "message": "A key does not match the input addresses.",
  "data": {
    "reason": "key_mismatch"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API403 (HTTP 403): Forbidden

The envelope (`op: "send"`) names the recipients and amounts in `bind.to` (base-unit integer strings, plus `bind.token` for a token transfer). The signer decodes the transaction itself and refuses unless it pays exactly those and any other output returns to an input address; nothing is signed.

```json
{
  "status": 0,
  "code": "API403",
  "message": "The outputs are not the ones the envelope names.",
  "data": {
    "reason": "outputs_not_bound"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

The envelope is unreadable, is a v1 envelope, names an unknown `kid`, has an `op` that does not match the route, or has an `exp` more than 300 seconds ahead. Fetch [tx/signer-key](https://docs.rarebl.com/api/tx/signer-key) again and encrypt again with SDK 0.2.0 or later.

```json
{
  "status": 0,
  "code": "API400",
  "message": "The envelope could not be read.",
  "data": {
    "reason": "bad_envelope"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

The envelope's `exp` has passed. Make a new envelope right before the request.

```json
{
  "status": 0,
  "code": "API400",
  "message": "The envelope has expired.",
  "data": {
    "reason": "envelope_expired"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API409 (HTTP 409): Conflict

An envelope opens once. Make a new envelope for every request, including a retry.

```json
{
  "status": 0,
  "code": "API409",
  "message": "The envelope was already used.",
  "data": {
    "reason": "envelope_replayed"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

The `chain` in the envelope is not the chain of the request.

```json
{
  "status": 0,
  "code": "API400",
  "message": "The envelope is for another chain.",
  "data": {
    "reason": "chain_mismatch"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

The selected inputs cannot pay the outputs plus the fee.

```json
{
  "status": 0,
  "code": "API422",
  "message": "The inputs do not cover the amount and the fee.",
  "data": {
    "reason": "insufficient_funds"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API422 (HTTP 422): Unprocessable Entity

The node refused it. `data.detail` carries its message.

```json
{
  "status": 0,
  "code": "API422",
  "message": "The node rejected the transaction.",
  "data": {
    "reason": "node_rejected",
    "detail": "min relay fee not met"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (write class: 6 per minute, burst 3, 300 per day, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- A tx/build body plus `keys`. This really broadcasts. See [Hosted signing](https://docs.rarebl.com/guides/hosted-signing).
- The same safeguards as tx/sign apply: risk header, body-only keys, key matching, no retention, at most 10 inputs, write class. The envelope (`op: "send"`) carries `bind`, the recipients and amounts it allows; build it with `envelope.bindOf`.

---

# New address and key (hosted)

`POST https://api.rarebl.com/open/address/new`

Generates a new keypair inside the signer, never stores it, and returns it once. The SDKs can also generate keys locally (`keys.generate`).

**Rate class:** write (6 per minute, burst 3, 300 per day, per IP). **Available since:** Open API v2.

**Try It is disabled for this endpoint.** A documentation page should never collect private keys, so Try It is off here. Use the snippets from your own server or an SDK.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/address/new" -H "Content-Type: application/json" -H "X-Rarebl-Accept-Risk: hosted-signing" -d '{"chain":"btc","type":"p2wpkh"}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Rarebl-Accept-Risk` | Yes | Required acknowledgement that you are sending private keys to a hosted signer. The only accepted value is `hosted-signing`; without it the API answers `API403` `risk_not_acknowledged`. Example: `hosted-signing`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain. One of: btc, ltc, bch, dash, eth, tron. |
| `type` | string | No | Address type, for example `p2wpkh`, `p2pkh`, `p2tr`. One of: p2wpkh, p2pkh, p2sh-p2wpkh, p2tr. |
| `encryptTo` | string | No | Your X25519 public key (base64url). When set, the private key comes back as `encryptedPrivateKey`, an envelope v2 of the same scheme in the other direction (`kid: "client"`); open it with `envelope.decrypt`. |

## Responses

### API200 (HTTP 200): OK

A new keypair. With `encryptTo` the key is returned as `encryptedPrivateKey`.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "address": "bc1q9n6w0t7m5x3k2a8d4h1j6f0s5g7c3v2b8l4e9z",
    "publicKey": "02f1a6c3d9e7b04a52c8e1d36f7094ba5c21e8d03f6a97b4c15e2d80a3f6b79c41",
    "encryptedPrivateKey": "BASE64URL_ENVELOPE_ENCRYPTED_TO_YOUR_X25519_KEY",
    "wif": null
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.address / publicKey` | string | The new address and its public key. |
| `data.privateKey \| encryptedPrivateKey` | string | The private key (plain) or, with `encryptTo`, encrypted to your key. Shown once; never stored. |
| `data.wif` | string \| null | The WIF for UTXO chains. |

### API403 (HTTP 403): Forbidden

The header `X-Rarebl-Accept-Risk: hosted-signing` is missing.

```json
{
  "status": 0,
  "code": "API403",
  "message": "Hosted signing needs the risk acknowledgement header.",
  "data": {
    "reason": "risk_not_acknowledged"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Unknown or missing chain.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (write class: 6 per minute, burst 3, 300 per day, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Use `encryptTo` to receive the private key encrypted to your own X25519 key. The plaintext of `encryptedPrivateKey` is `{"privateKeys": ["<64-hex>"]}` and the WIF is omitted in this mode. To generate keys on your machine instead, use the [SDK](https://docs.rarebl.com/guides/sign-locally) (`keys.generate`).
- The keypair is generated in the signer process and never stored. The example shows `encryptedPrivateKey` as a placeholder; no real key appears in these docs.

---

# Validate an address

`GET https://api.rarebl.com/open/address/validate`

Checks that an address is well formed for a chain and returns its type and normalized form. For ETH it also tells whether the address is a contract.

**Rate class:** compute (2 requests per second, burst 10, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/address/validate?chain=btc&address=bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | The chain. One of: btc, ltc, bch, dash, eth, tron. |
| `address` | string | Yes | The address to check. |

## Responses

### API200 (HTTP 200): OK

A valid Bitcoin address.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "valid": true,
    "type": "p2wpkh",
    "normalized": "bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.valid` | boolean | Whether the address is valid for the chain. |
| `data.type` | string | p2pkh, p2sh, p2wpkh, p2tr, cashaddr, eoa, contract, tron-account, ... |
| `data.normalized` | string | The canonical form (BCH: CashAddr without prefix; ETH: checksummed). |
| `data.isContract` | boolean | ETH only, from `eth_getCode`. |

### API200 (HTTP 200): OK (ETH)

An ETH contract address.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "valid": true,
    "type": "contract",
    "normalized": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "isContract": true
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `chain`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Unknown or missing chain.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (compute class: 2 requests per second, burst 10, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Mostly pure code (checksums and prefixes); ETH adds an `eth_getCode` call.
- Use it before saving a withdrawal address.

---

# Watch addresses

`POST https://api.rarebl.com/open/address/watch`

Starts tracking BTC, LTC or BCH addresses (their UTXOs and activity) so that UTXOs, balances and webhooks become exact.

**Rate class:** watch (30 per minute, 2,000 addresses per day, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/address/watch" -H "Content-Type: application/json" -d '{"chain":"btc","addresses":["bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q","bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm"]}'`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | BTC, LTC or BCH. One of: btc, ltc, bch. |
| `addresses` | array | Yes | Up to 100 addresses. At most 100 per call. |

## Responses

### API200 (HTTP 200): OK

Each address is `pending` until its bootstrap is done, then `active`.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "watches": [
      {
        "address": "bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q",
        "status": "pending",
        "since": "2026-11-15T01:12:07Z"
      },
      {
        "address": "bc1qanfrvw5lunlemvm09dthnxmwknal0fw0q7jfnm",
        "status": "active",
        "since": "2026-11-14T21:03:55Z"
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.watches[]` | object[] | `{address, status: "pending" \| "active", since}`. |

### API400 (HTTP 400): Bad Request

The chain is missing, or is not BTC, LTC or BCH (DASH and the account chains do not need a watch).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Unknown or missing chain.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (watch class: 30 per minute, 2,000 addresses per day). `Retry-After` says how long to wait.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- A UTXO-set bootstrap runs first; the address then follows new blocks and the mempool. The watch is `active` once the bootstrap is done. How long that takes depends on the deployment and the chain: poll this endpoint (or [address/utxos](https://docs.rarebl.com/api/address/utxos)) until the status is `active`.
- While an address is watched and active, [Address](https://docs.rarebl.com/api/address/balance) also returns an exact balance on BTC, LTC and BCH (`balanceStatus: "exact"`).
- Watches expire after 90 days without a query or webhook. Any read renews them.
- Not needed on DASH or the account chains. Address webhooks and WebSocket address channels on BTC/LTC/BCH watch the address automatically.

---

# Address UTXOs

`GET https://api.rarebl.com/open/address/utxos`

The unspent outputs and balance of an address, for sweeps and payouts. BTC, LTC and BCH addresses must be watched and active; DASH uses its node index.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/address/utxos?chain=dash&address=XnL1FvTKqe6aWfB8NrvgbUMuWCEA3dNxfF"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | A UTXO chain. One of: btc, ltc, bch, dash. |
| `address` | string | Yes | The address. |
| `minConf` | integer | No | Minimum confirmations. Default 0. |

## Responses

### API200 (HTTP 200): OK

One unspent output (a real Dash reply).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "utxos": [
      {
        "txid": "1fa1b672aa5ef13127ede15aeef61c5fe3ec8565031cd826f65e6a332baefb9c",
        "vout": 1,
        "value": "4.23877346",
        "valueSats": 423877346,
        "height": 2572425,
        "confirmations": 2,
        "scriptPubKey": "76a9147fb0a45f00c25ff1cb67753221326c7c420b8b2388ac"
      }
    ],
    "balance": "4.23877346",
    "balanceSats": 423877346
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.utxos[]` | object[] | `{txid, vout, value, valueSats, height \| null, confirmations, scriptPubKey}`. |
| `data.balance / balanceSats` | string | The sum of the returned UTXOs. |

### API409 (HTTP 409): Conflict

BTC, LTC or BCH: the address is not watched and active. `data.watch` names the call that starts one ([address/watch](https://docs.rarebl.com/api/address/watch)).

```json
{
  "status": 0,
  "code": "API409",
  "message": "address is not watched yet: POST address/watch first",
  "data": {
    "reason": "not_watched",
    "watch": {
      "chain": "btc",
      "address": "bc1q7dszvzdj8lk8dd4ssad94m0t2acunaf48j455q",
      "endpoint": "address/watch"
    }
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API400 (HTTP 400): Bad Request

ETH and TRON have no UTXOs: they answer API400.

```json
{
  "status": 0,
  "code": "API400",
  "message": "UTXOs exist on UTXO chains only.",
  "data": {
    "param": "chain"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Spend them with [Build a transaction](https://docs.rarebl.com/api/tx/build) and `inputs`, or let the SDK pick them: see [Watch addresses, get UTXOs and balances](https://docs.rarebl.com/guides/watch-addresses).

---

# Address nonce (ETH)

`GET https://api.rarebl.com/open/address/nonce`

The latest and pending transaction count of an Ethereum address, to set the nonce of the next transaction.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/address/nonce?chain=eth&address=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | Ethereum only. One of: eth. |
| `address` | string | Yes | The ETH address. |

## Responses

### API200 (HTTP 200): OK

Latest and pending nonce.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "latest": 42,
    "pending": 42
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.latest / pending` | integer | Confirmed and pending transaction counts. Use `pending` for the next transaction. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `address`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Invalid ETH address.",
  "data": {
    "param": "address"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- ETH depends on the Ethereum node, which is still syncing: expect `API502` until it has finished.
- [Build a transaction](https://docs.rarebl.com/api/tx/build) fills the nonce for you.

---

# Address resources (TRON)

`GET https://api.rarebl.com/open/address/resources`

The energy and bandwidth of a TRON account, and its frozen balances, to know whether a transfer burns TRX.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/address/resources?chain=tron&address=TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | TRON only. One of: tron. |
| `address` | string | Yes | The TRON address. |

## Responses

### API200 (HTTP 200): OK

Resources of an account with no staked energy (a real TRON reply).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "energy": {
      "limit": 0,
      "used": 0,
      "available": 0
    },
    "bandwidth": {
      "free": 600,
      "staked": 0,
      "used": 158,
      "available": 442
    },
    "frozen": []
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.energy` | object | `{limit, used, available}`. |
| `data.bandwidth` | object | `{free, staked, used, available}`. |
| `data.frozen[]` | object[] | Frozen (staked) balances. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `address`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Invalid TRON address.",
  "data": {
    "param": "address"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API502 (HTTP 502): Bad Gateway

The node is unavailable, still syncing or timed out. Retry later with a short back-off.

```json
{
  "status": 0,
  "code": "API502",
  "message": "The node is unavailable or timed out. Please try again.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Compare with the `energy` and `bandwidth` from [Estimate a transaction](https://docs.rarebl.com/api/tx/estimate): what you lack is burned as TRX.

---

# Create a webhook

`POST https://api.rarebl.com/open/hooks/create`

Creates a webhook subscription. There are no accounts: the reply carries a management token and a signing secret, both shown once.

**Rate class:** hooks (10 per minute, at most 100 active subscriptions per IP, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/hooks/create" -H "Content-Type: application/json" -d '{"type":"tx.confirmations","chain":"btc","url":"https://example.com/hooks/rarebl","txid":"9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db","confirmations":6}'`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | What to subscribe to. One of: block.new, tx.confirmations, address.activity, token.transfer. |
| `chain` | string | Yes | The chain. One of: btc, ltc, bch, dash, eth, tron. |
| `url` | string | Yes | Your `https://` endpoint on port 443 or 8443. Private, loopback, link-local and reserved IPs are refused; redirects are not followed. |
| `txid` | string | No | `tx.confirmations`: the transaction to follow. |
| `address` | string | No | `address.activity` (and `token.transfer`): the address to follow. |
| `contract` | string | No | `token.transfer`: the token contract to follow (ETH, TRON). |
| `confirmations` | integer | No | Confirmation threshold for `tx.confirmations` and `address.activity`. 0 to 100 Default 6. |

## Responses

### API200 (HTTP 200): OK

The subscription. `manageToken` and `signingSecret` are shown once: store them now.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "id": "hk_3f9a2c71e0b84d56",
    "manageToken": "mt_7c1d0e94a2b64f3880c5e1a9d27b6f40",
    "signingSecret": "whsec_b81f4a9c20de7536a1c4f08e93d2b715",
    "type": "tx.confirmations",
    "chain": "btc",
    "url": "https://example.com/hooks/rarebl",
    "txid": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
    "confirmations": 6,
    "status": "active",
    "createdAt": "2026-11-15T01:12:07Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.id` | string | The subscription id. |
| `data.manageToken` | string | Authorizes every other hooks call (`X-Hook-Token`). Shown once. |
| `data.signingSecret` | string | Key of the `X-Rarebl-Signature` HMAC on every delivery. Shown once. |

### API400 (HTTP 400): Bad Request

The URL is not https on port 443 or 8443, or points to a private, loopback, link-local or reserved address.

```json
{
  "status": 0,
  "code": "API400",
  "message": "url must be an https URL on port 443 or 8443.",
  "data": {
    "param": "url"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (hooks class: 10 per minute, at most 100 active subscriptions per IP, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Both secrets are returned once and cannot be shown again. Lose the token and you cannot manage the hook; lose the secret and you cannot verify deliveries (create a new subscription).
- Rate limit: 10 per minute, at most 100 active subscriptions per IP.
- In Try It, the `id` and token from this reply are saved in your browser and prefilled on the other webhook pages. **Reset saved Try It values** in the settings menu clears them.
- Events, signatures, retries and source IPs: [Webhooks](https://docs.rarebl.com/guides/webhooks). The reply carries `id`, `manageToken` and `signingSecret`, plus the subscription fields.

---

# Get a webhook

`GET https://api.rarebl.com/open/hooks/get`

Reads a subscription. Secrets are not returned again.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/hooks/get?id=hk_3f9a2c71e0b84d56"`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Hook-Token` | Yes | The `manageToken` returned once by [hooks/create](https://docs.rarebl.com/api/hooks/create). Sent in a header, never in the URL. Example: `YOUR_MANAGE_TOKEN`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook subscription id returned by hooks/create. |

## Responses

### API200 (HTTP 200): OK

The subscription.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "id": "hk_3f9a2c71e0b84d56",
    "type": "tx.confirmations",
    "chain": "btc",
    "url": "https://example.com/hooks/rarebl",
    "txid": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
    "confirmations": 6,
    "status": "active",
    "createdAt": "2026-11-15T01:12:07Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The webhook does not exist.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Webhook not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Needs the header `X-Hook-Token: <manageToken>`.

---

# Update a webhook

`POST https://api.rarebl.com/open/hooks/update`

Changes fields of a subscription, for example its URL or confirmation threshold.

**Rate class:** hooks (10 per minute, at most 100 active subscriptions per IP, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/hooks/update" -H "Content-Type: application/json" -H "X-Hook-Token: YOUR_MANAGE_TOKEN" -d '{"id":"hk_3f9a2c71e0b84d56"}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Hook-Token` | Yes | The `manageToken` returned once by [hooks/create](https://docs.rarebl.com/api/hooks/create). Sent in a header, never in the URL. Example: `YOUR_MANAGE_TOKEN`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook subscription id returned by hooks/create. |
| `url` | string | No | A new https URL. |
| `confirmations` | integer | No | A new threshold. 0 to 100 |

## Responses

### API200 (HTTP 200): OK

The updated subscription.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "id": "hk_3f9a2c71e0b84d56",
    "type": "tx.confirmations",
    "chain": "btc",
    "url": "https://example.com/hooks/rarebl",
    "txid": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
    "confirmations": 12,
    "status": "active",
    "createdAt": "2026-11-15T01:12:07Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The webhook does not exist.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Webhook not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (hooks class: 10 per minute, at most 100 active subscriptions per IP, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Takes `id` plus the fields you want to change. Needs `X-Hook-Token`.

---

# Pause a webhook

`POST https://api.rarebl.com/open/hooks/pause`

Stops deliveries without deleting the subscription.

**Rate class:** hooks (10 per minute, at most 100 active subscriptions per IP, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/hooks/pause" -H "Content-Type: application/json" -H "X-Hook-Token: YOUR_MANAGE_TOKEN" -d '{"id":"hk_3f9a2c71e0b84d56"}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Hook-Token` | Yes | The `manageToken` returned once by [hooks/create](https://docs.rarebl.com/api/hooks/create). Sent in a header, never in the URL. Example: `YOUR_MANAGE_TOKEN`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook subscription id returned by hooks/create. |

## Responses

### API200 (HTTP 200): OK

The paused subscription.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "id": "hk_3f9a2c71e0b84d56",
    "type": "tx.confirmations",
    "chain": "btc",
    "url": "https://example.com/hooks/rarebl",
    "txid": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
    "confirmations": 6,
    "status": "paused",
    "createdAt": "2026-11-15T01:12:07Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The webhook does not exist.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Webhook not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (hooks class: 10 per minute, at most 100 active subscriptions per IP, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Needs `X-Hook-Token`. A subscription is also paused automatically after 20 consecutive failed deliveries; [Resume](https://docs.rarebl.com/api/hooks/resume) it once your endpoint is fixed.

---

# Resume a webhook

`POST https://api.rarebl.com/open/hooks/resume`

Restarts deliveries of a paused subscription.

**Rate class:** hooks (10 per minute, at most 100 active subscriptions per IP, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/hooks/resume" -H "Content-Type: application/json" -H "X-Hook-Token: YOUR_MANAGE_TOKEN" -d '{"id":"hk_3f9a2c71e0b84d56"}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Hook-Token` | Yes | The `manageToken` returned once by [hooks/create](https://docs.rarebl.com/api/hooks/create). Sent in a header, never in the URL. Example: `YOUR_MANAGE_TOKEN`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook subscription id returned by hooks/create. |

## Responses

### API200 (HTTP 200): OK

The active subscription.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "id": "hk_3f9a2c71e0b84d56",
    "type": "tx.confirmations",
    "chain": "btc",
    "url": "https://example.com/hooks/rarebl",
    "txid": "9dedeb8092d6f026d235e3beb24337ba5657635a38cc949f70c0f28ea15e30db",
    "confirmations": 6,
    "status": "active",
    "createdAt": "2026-11-15T01:12:07Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The webhook does not exist.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Webhook not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (hooks class: 10 per minute, at most 100 active subscriptions per IP, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Needs `X-Hook-Token`.

---

# Delete a webhook

`POST https://api.rarebl.com/open/hooks/delete`

Deletes a subscription permanently.

**Rate class:** hooks (10 per minute, at most 100 active subscriptions per IP, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/hooks/delete" -H "Content-Type: application/json" -H "X-Hook-Token: YOUR_MANAGE_TOKEN" -d '{"id":"hk_3f9a2c71e0b84d56"}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Hook-Token` | Yes | The `manageToken` returned once by [hooks/create](https://docs.rarebl.com/api/hooks/create). Sent in a header, never in the URL. Example: `YOUR_MANAGE_TOKEN`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook subscription id returned by hooks/create. |

## Responses

### API200 (HTTP 200): OK

Deleted.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "id": "hk_3f9a2c71e0b84d56",
    "deleted": true
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The webhook does not exist.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Webhook not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (hooks class: 10 per minute, at most 100 active subscriptions per IP, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Needs `X-Hook-Token`. This cannot be undone.

---

# Webhook deliveries

`GET https://api.rarebl.com/open/hooks/deliveries`

The last 100 delivery attempts of a subscription, to debug your endpoint.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/hooks/deliveries?id=hk_3f9a2c71e0b84d56"`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Hook-Token` | Yes | The `manageToken` returned once by [hooks/create](https://docs.rarebl.com/api/hooks/create). Sent in a header, never in the URL. Example: `YOUR_MANAGE_TOKEN`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook subscription id returned by hooks/create. |

## Responses

### API200 (HTTP 200): OK

The last 100 delivery attempts.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "deliveries": [
      {
        "eventId": "evt_01hx9k2p4m",
        "type": "tx.confirmations",
        "attempt": 1,
        "status": "delivered",
        "httpStatus": 200,
        "durationMs": 184,
        "at": "2026-11-15T01:18:12Z"
      },
      {
        "eventId": "evt_01hx9k1c7q",
        "type": "tx.confirmations",
        "attempt": 2,
        "status": "failed",
        "httpStatus": 503,
        "durationMs": 9021,
        "at": "2026-11-15T01:15:03Z"
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The webhook does not exist.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Webhook not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Needs `X-Hook-Token`. Use it with [Replay](https://docs.rarebl.com/api/hooks/replay) to re-send an event your endpoint missed.

---

# Send a test event

`POST https://api.rarebl.com/open/hooks/test`

Sends a signed sample event to your URL so you can test signature verification.

**Rate class:** hooks (10 per minute, at most 100 active subscriptions per IP, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/hooks/test" -H "Content-Type: application/json" -H "X-Hook-Token: YOUR_MANAGE_TOKEN" -d '{"id":"hk_3f9a2c71e0b84d56"}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Hook-Token` | Yes | The `manageToken` returned once by [hooks/create](https://docs.rarebl.com/api/hooks/create). Sent in a header, never in the URL. Example: `YOUR_MANAGE_TOKEN`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook subscription id returned by hooks/create. |

## Responses

### API200 (HTTP 200): OK

Queued.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "eventId": "evt_test_5d8e2a",
    "type": "tx.confirmations",
    "queued": true
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The webhook does not exist.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Webhook not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (hooks class: 10 per minute, at most 100 active subscriptions per IP, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Needs `X-Hook-Token`. The event is signed exactly like a real one: see [Webhooks](https://docs.rarebl.com/guides/webhooks).

---

# Replay an event

`POST https://api.rarebl.com/open/hooks/replay`

Re-sends a past event to your URL.

**Rate class:** hooks (10 per minute, at most 100 active subscriptions per IP, per IP). **Available since:** Open API v2.

## Request

Send a JSON body (`Content-Type: application/json`). No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl -X POST "https://api.rarebl.com/open/hooks/replay" -H "Content-Type: application/json" -H "X-Hook-Token: YOUR_MANAGE_TOKEN" -d '{"id":"hk_3f9a2c71e0b84d56","eventId":"evt_01hx9k1c7q"}'`

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `X-Hook-Token` | Yes | The `manageToken` returned once by [hooks/create](https://docs.rarebl.com/api/hooks/create). Sent in a header, never in the URL. Example: `YOUR_MANAGE_TOKEN`. |

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook subscription id returned by hooks/create. |
| `eventId` | string | Yes | The event id (`X-Rarebl-Event-Id`) to re-send. |

## Responses

### API200 (HTTP 200): OK

Queued.

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "eventId": "evt_01hx9k1c7q",
    "queued": true
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API404 (HTTP 404): Not Found

The webhook does not exist.

```json
{
  "status": 0,
  "code": "API404",
  "message": "Webhook not found.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (hooks class: 10 per minute, at most 100 active subscriptions per IP, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Needs `X-Hook-Token`. Find event ids with [Deliveries](https://docs.rarebl.com/api/hooks/deliveries).

---

# Prices

`GET https://api.rarebl.com/open/market/price`

Reference prices aggregated from public exchange feeds: the median of fresh sources, outliers more than 2% from the median excluded. Not Rarebl trading rates.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/market/price?assets=btc%2Ceth&quote=usd"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `assets` | string | Yes | Comma-separated asset symbols. |
| `quote` | string | No | Quote currency. Besides usd, eur, gbp, ghs and ngn are derived through FX. Default usd. One of: usd, eur, gbp, ghs, ngn. |

## Responses

### API200 (HTTP 200): OK

Prices (a real reply, shortened).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "prices": [
      {
        "asset": "BTC",
        "quote": "USD",
        "price": "63421.45",
        "change24h": "-7.1155",
        "sources": [
          {
            "id": "binance",
            "pair": "BTC/USD",
            "price": 63449.83,
            "volume": 11.75039
          },
          {
            "id": "kraken",
            "pair": "BTC/USD",
            "price": 63426.4,
            "volume": 5752.38744852
          },
          {
            "id": "coinbase",
            "pair": "BTC/USD",
            "price": 63421.45,
            "volume": 16529.56926348
          }
        ],
        "stale": false,
        "updatedAt": "2026-11-15T01:00:51.309Z"
      },
      {
        "asset": "ETH",
        "quote": "USD",
        "price": "1741.94",
        "change24h": "-9.7052",
        "sources": [
          {
            "id": "binance",
            "pair": "ETH/USD",
            "price": 1742.98,
            "volume": 122.249
          },
          {
            "id": "kraken",
            "pair": "ETH/USD",
            "price": 1740.61,
            "volume": 63575.06022326
          },
          {
            "id": "coinbase",
            "pair": "ETH/USD",
            "price": 1740.96,
            "volume": 265726.23468535
          }
        ],
        "stale": false,
        "updatedAt": "2026-11-15T01:00:51.437Z"
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.prices[]` | object[] | `{asset, quote, price, change24h, sources[], stale, updatedAt}`. |
| `prices[].stale` | boolean | true when fresh sources are missing. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `assets`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Missing parameter: assets.",
  "data": {
    "param": "assets"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- **Reference prices, not trading rates.** Rarebl does not guarantee that you can trade at these prices. See [Market data and fees](https://docs.rarebl.com/guides/market-data).
- Sources are attributed in `sources`. Check `stale` before you display a price.

---

# Tickers

`GET https://api.rarebl.com/open/market/tickers`

The individual exchange tickers behind a price.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/market/tickers?asset=btc"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `asset` | string | Yes | An asset symbol. |

## Responses

### API200 (HTTP 200): OK

Tickers by source (a real reply, shortened).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "tickers": [
      {
        "source": "binance",
        "pair": "BTC/USD",
        "last": "63449.83",
        "bid": "63392.39",
        "ask": "63437.98",
        "volume24h": "11.75039",
        "ts": "2026-11-15T01:00:51.309Z"
      },
      {
        "source": "bitfinex",
        "pair": "BTC/USD",
        "last": "63499",
        "bid": "63495",
        "ask": "63502",
        "volume24h": "1644.58469326",
        "ts": "2026-11-15T01:00:45.910Z"
      },
      {
        "source": "bitstamp",
        "pair": "BTC/USD",
        "last": "63413.18",
        "bid": "63407.27",
        "ask": "63407.28",
        "volume24h": "1899.15444542",
        "ts": "2026-11-15T01:00:44.225Z"
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.tickers[]` | object[] | `{source, pair, last, bid, ask, volume24h, ts}`. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `asset`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Missing parameter: asset.",
  "data": {
    "param": "asset"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Reference data from public feeds, not Rarebl trading rates.

---

# Price history

`GET https://api.rarebl.com/open/market/history`

OHLCV candles for an asset.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/market/history?asset=btc&quote=usd&interval=1h"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `asset` | string | Yes | An asset symbol. |
| `quote` | string | No | Quote currency. Default usd. One of: usd, eur, gbp, ghs, ngn. |
| `interval` | string | Yes | Candle size. One of: 1m, 1h, 1d. |
| `from` | string | No | Start time (ISO 8601). |
| `to` | string | No | End time (ISO 8601). |

## Responses

### API200 (HTTP 200): OK

Candles (a real reply).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "candles": [
      {
        "ts": "2026-11-14T23:00:00.000Z",
        "open": "64136.4",
        "high": "64174.2",
        "low": "64068.4",
        "close": "64139.5",
        "volume": null
      },
      {
        "ts": "2026-11-15T00:00:00.000Z",
        "open": "64123.32",
        "high": "64469.5",
        "low": "63430.38",
        "close": "63478.34",
        "volume": null
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.candles[]` | object[] | `{ts, open, high, low, close, volume}`. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `interval`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Missing parameter: interval.",
  "data": {
    "param": "interval"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- At most 1,000 candles per call.
- Reference data, not Rarebl trading rates.

---

# Assets

`GET https://api.rarebl.com/open/market/assets`

The assets with prices: symbol, name, chain, token contract and decimals.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/market/assets"`

## Parameters

This endpoint takes no parameters.

## Responses

### API200 (HTTP 200): OK

Assets (shortened).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "assets": [
      {
        "symbol": "BTC",
        "name": "Bitcoin",
        "chain": "btc",
        "contract": null,
        "decimals": 8
      },
      {
        "symbol": "ETH",
        "name": "Ether",
        "chain": "eth",
        "contract": null,
        "decimals": 18
      },
      {
        "symbol": "LTC",
        "name": "Litecoin",
        "chain": "ltc",
        "contract": null,
        "decimals": 8
      },
      {
        "symbol": "TRX",
        "name": "TRON",
        "chain": "tron",
        "contract": null,
        "decimals": 6
      },
      {
        "symbol": "USDC",
        "name": "USD Coin (ERC-20)",
        "chain": "eth",
        "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "decimals": 6
      },
      {
        "symbol": "USDT",
        "name": "Tether USD (ERC-20)",
        "chain": "eth",
        "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "decimals": 6
      },
      {
        "symbol": "USDT-TRON",
        "name": "Tether USD (TRC-20)",
        "chain": "tron",
        "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "decimals": 6
      }
    ]
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.assets[]` | object[] | `{symbol, name, chain, contract \| null, decimals}`. |

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Use it to map a token contract to a price symbol.

---

# FX rates

`GET https://api.rarebl.com/open/market/fx`

Foreign-exchange reference rates, for example usd to ghs and ngn.

**Rate class:** read (5 requests per second, burst 20, per IP). **Available since:** Open API v2.

## Request

Send the parameters as query parameters (GET) or as a JSON object (POST with `Content-Type: application/json`). They are identical either way. No API key is needed: `X-API-KEY` is reserved and ignored.

Example: `curl "https://api.rarebl.com/open/market/fx?base=usd&quotes=ghs%2Cngn"`

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `base` | string | No | Base currency. Default usd. |
| `quotes` | string | Yes | Comma-separated quote currencies. |

## Responses

### API200 (HTTP 200): OK

Rates (a real reply).

```json
{
  "status": 1,
  "code": "API200",
  "message": "success",
  "data": {
    "rates": {
      "GHS": "11.747527",
      "NGN": "1352.072165"
    },
    "source": "er-api",
    "updatedAt": "2026-11-15T00:37:02.017Z"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `data.rates` | object | Quote currency to rate. |
| `data.source / updatedAt` | string | The feed behind it and when it was updated. |

### API400 (HTTP 400): Bad Request

A parameter is missing or malformed. `data.param` names it (here `quotes`).

```json
{
  "status": 0,
  "code": "API400",
  "message": "Missing parameter: quotes.",
  "data": {
    "param": "quotes"
  },
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

### API429 (HTTP 429): Too Many Requests

Rate limited (read class: 5 requests per second, burst 20, per IP). A `Retry-After` header says how long to wait, in seconds.

```json
{
  "status": 0,
  "code": "API429",
  "message": "Too many requests. Please retry shortly.",
  "data": null,
  "go": null,
  "meta": {
    "requestid": "0123456789abcdef",
    "notices": []
  }
}
```

## Notes

- Reference rates, not Rarebl trading rates.

---

# WebSocket stream

`wss://api.rarebl.com/ws` pushes live events: new blocks, fees, address activity, transaction progress and token transfers. It is keyless like the rest of the API. This is a reference page: there is no Try It for a WebSocket, so use the examples below from your own client. For a walkthrough see [Live data over WebSocket](https://docs.rarebl.com/guides/websocket).

## Connect

```js JavaScript
const ws = new WebSocket('wss://api.rarebl.com/ws');

ws.onopen = () => ws.send(JSON.stringify({
  op: 'subscribe',
  channels: ['blocks:btc', 'live', 'fees:eth'],
}));

ws.onmessage = (msg) => {
  const m = JSON.parse(msg.data);
  if (m.op === 'ping') return ws.send(JSON.stringify({ op: 'pong' }));
  console.log(m);
};
```

## Messages

| Direction | Message | Meaning |
| --- | --- | --- |
| Client to server | `{"op":"subscribe","channels":[…]}` | Subscribe to channels. |
| Server to client | `{"op":"subscribed","channels":[…],"rejected":[{"channel","reason"}]}` | The channels now active, and any that were refused. Channels come back normalised (ETH lower-case, BCH CashAddr without the prefix). |
| Client to server | `{"op":"unsubscribe","channels":[…]}` | Stop receiving channels. |
| Server to client | `{"channel","type","data","ts"}` | An event on a channel. |
| Server to client | `{"op":"ping"}` every 20 s | Answer with `{"op":"pong"}`. Any message you send counts as life; 70 s of silence closes the socket. |
| Server to client | `{"op":"error","code","message"}` | A message was refused. |

## Channels

| Channel | Event data |
| --- | --- |
| `live` | The heads of all chains, like [Live stats](https://docs.rarebl.com/api/stats/live). The latest is replayed on subscribe. |
| `blocks:<chain>` | New blocks of a chain, for example `blocks:btc`. |
| `fees:<chain>` | Fee updates, for example `fees:eth`. |
| `address:<chain>:<address>` | Activity on an address. On BTC, LTC and BCH the address is **watched automatically**. |
| `tx:<chain>:<txid>` | Progress of a transaction, for example `tx:eth:0x…`. |
| `token:<chain>:<address>` | Token transfers to or from an address on ETH or TRON. |
| `token:<chain>:c:<contract>` | Token transfers of a contract on ETH or TRON. |

## Event types

`block.new`, `block.reorged`, `address.activity`, `tx.confirmations`, `tx.final`, `tx.dropped`, `tx.replaced`, `token.transfer`, `live` and `fees`. The `data` of each event follows the shapes in [Data types](https://docs.rarebl.com/data-types) and the webhook events in [Webhooks](https://docs.rarebl.com/guides/webhooks): read `type`, then treat `data` as the object for that kind of event.

## Limits

| Limit | Value |
| --- | --- |
| Connections | 3 per IP (the 4th is closed with code 1008) |
| Subscriptions | 200 channels per connection |
| Heartbeat | the server pings every 20 s; answer `{"op":"pong"}` |
| Slow clients | closed with code 1013 after 256 unacknowledged messages |
| Client messages | more than 60 in 10 s closes with 1008; frames are capped at 16 kB |

Reconnect with back-off after a drop, and resubscribe: subscriptions do not survive a dropped connection. A client that cannot keep up is disconnected rather than buffered without bound.

## Related

[Webhooks](https://docs.rarebl.com/guides/webhooks) for server-to-server delivery with retries; [Live stats](https://docs.rarebl.com/api/stats/live) to poll instead; [Rate limits](https://docs.rarebl.com/rate-limits) for the stream class.

---