Shell SDK
Download the rarebl command line tool (bash, curl, jq): keys, transfers and webhook checks from the terminal.
# 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).