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