Chand
A fast, elegant CLI for live currency and cryptocurrency prices in Iranian Rial and Toman.
Chand fetches free-market rates and crypto prices, falls back between providers when one is blocked or rate-limited, and renders a clean terminal table or stable JSON for scripts. It is built for the Iranian market context: the USD rate is the cash/free-market rate, and every price can be shown in Rial or Toman.
Features
- Broad coverage: 49 fiat currencies and 35 cryptocurrencies, including Gulf, Central Asian, Caucasus, and major global markets
- Iranian-first fallback: Nobitex, Wallex, NerkhAra, TGJU, Bonbast, CoinGecko, and ExchangeRate-API
- Nobitex
apiv2support with a legacy-domain mirror; TGJU bulk and profile parsing; Wallex and NerkhAra Toman rates - Rial and Toman output with correct market conversion (
1 Toman = 10 Rial) - Rich colorized tables with 24-hour change and the source used for each price
--watchlive refresh and-wsource-page opening in your browser- Machine-readable JSON and newline-delimited JSON for scripts
- Short-lived disk cache with
--no-cache; cache is bypassed during watch - Shell completion, typed exit codes, and friendly typo suggestions
- No API keys required; an optional CoinGecko demo key raises rate limits
Requirements
- Python 3.14+
- Internet access for live data
- uv (recommended)
Installation
git clone https://github.com/cmd-3324/Chand.git
cd Chand
uv sync
uv run chand --help
Install it as a global command:
uv tool install .
chand --version
pip works too:
python -m pip install -e .
chand --help
Usage
# Quick table: BTC, ETH, USDT, USD, EUR, GBP, AED, TRY, CNY, JPY, CAD, XRP
chand
# Open the quick table's source pages
chand -w
# Supported assets, names, and aliases
chand list
# Quote one asset in Rial
chand price BTC --unit rial
# Quote several assets in Toman (default)
chand price BTC ETH USD EUR
# Select by kind, or quote everything
chand price --currency USD,EUR
chand price --crypto BTC,ETH
chand price --all
# Refresh every 5 seconds until Ctrl+C
chand price BTC --watch 5
# Open the source page for each result in your default browser
chand price BTC -w
chand price BTC ETH -w
# Machine-readable output
chand price BTC --format json
chand list --format json
# Cache maintenance
chand cache path
chand cache clear # remove the quotes file only
chand cache purge # confirm y/N, then remove the whole cache directory
chand cache purge --yes # skip the prompt for scripts
Price options
| Flag | Meaning |
|---|---|
--unit, -u rial|toman |
Output unit (default Toman) |
--format, -f table|json |
Human table or machine JSON |
--watch N |
Refresh every N seconds (minimum 1) |
--all, -a |
Quote every supported asset |
--currency USD,EUR |
Select fiat currencies |
--crypto BTC,ETH |
Select cryptocurrencies |
--web, -w |
Open the source page for each result |
--no-cache |
Ignore and do not write cached quotes |
--timeout SECONDS |
Override the HTTP timeout |
--no-color |
Disable ANSI colors |
list accepts --currency, --crypto, --format, --web, and
--no-color.
Selecting assets
- Positional symbols accept case-insensitive names and aliases:
btc,xbt,Dollar,us$. - Use either positional symbols,
--all, or--currency/--crypto; mixing them is rejected so intent stays unambiguous. --currencyand--cryptoaccept comma-separated values and validate the asset kind (--currency BTCfails with a helpful hint).
Watch mode
--watch N re-fetches every N seconds (minimum 1), bypasses the cache, and
stops cleanly on Ctrl+C with exit code 130.
With --format json, watch mode emits one compact JSON array per line
(NDJSON), which is easy to pipe into jq or another process.
Opening source pages
-w / --web opens the page where the displayed value came from. Notes:
- One tab per selected asset, at most 10 at a time.
--watch -wopens pages once, not on every refresh.- In JSON mode Chand prints the URLs to stderr instead of opening tabs, keeping stdout clean for scripts.
- If no browser can be launched, Chand warns and still prints the prices.
Output
Table
Chand - live prices
Asset | Name | Price (Toman) | 24h | Source
-------+-----------+----------------+--------+-----------
BTC | Bitcoin | 19,048,850,700 | -1.79% | CoinGecko
USD | US Dollar | 259,900 | -1.54% | TGJU
The caption shows the local update time, the USD/IRR rate used for conversion, and the providers that answered.
JSON
[
{
"symbol": "BTC",
"name": "Bitcoin",
"kind": "crypto",
"unit": "toman",
"price": 19048850700,
"price_irr": 190488507000,
"price_toman": 19048850700,
"price_usd": 73293.0,
"change_24h": -1.7947,
"source": "CoinGecko",
"source_url": "https://www.coingecko.com/en/coins/bitcoin",
"fetched_at": "2026-11-10T19:24:52.375127+00:00"
}
]
pricefollows--unit;price_irrandprice_tomanare always present.- Large Rial/Toman values are JSON integers; small values such as SHIB or PEPE retain meaningful decimal precision. USD and percentage values are rounded JSON numbers.
- Fatal errors in JSON mode are written to stderr as
{"error": {"kind", "message", "hint", "exit_code"}}.
Configuration
Environment variables are optional; CLI flags win over environment values.
| Variable | Values | Default | Purpose |
|---|---|---|---|
CHAND_UNIT |
rial, toman |
toman |
Default output unit |
CHAND_FORMAT |
table, json |
table |
Default output format |
CHAND_TIMEOUT |
seconds | 10 |
HTTP timeout |
CHAND_CACHE_TTL |
seconds | 30 |
Quote cache lifetime; 0 disables |
CHAND_CACHE_DIR |
path | platform cache dir | Override the cache directory |
CHAND_WATCH |
seconds | 5 |
Default interval used by --watch |
CHAND_PROVIDERS |
comma list | all | Provider order/enablement |
CHAND_COINGECKO_API_KEY |
string | unset | CoinGecko demo API key |
CHAND_NO_COLOR |
1, true |
unset | Disable colors |
NO_COLOR |
any | unset | Standard no-color convention |
Available provider names: nobitex, wallex, nerkhara, tgju, bonbast,
coingecko, erapi. For example,
CHAND_PROVIDERS=wallex,tgju,bonbast restricts Chand to Iranian sources.
Data sources and fallback
Default order:
- Nobitex — crypto and USDT priced directly in Rial; uses
apiv2first with the legacy API domain as a mirror. - Wallex — crypto markets priced directly in Toman, normalized to Rial.
- NerkhAra — 44 fiat currencies and USDT in Toman from a compact JSON API.
- TGJU — 49 fiat profiles in Rial; one bulk request for large selections, with per-profile fallback for currencies outside the bulk table.
- Bonbast — 28 fiat currencies in Toman and Bitcoin in USD.
- CoinGecko — broad crypto coverage in USD; converted with the market USD/IRR rate.
- ExchangeRate-API — USD cross-rates as a final fiat fallback, including currencies not covered by Iranian sources.
TGJU quotes Japanese yen per 100 yen, Bonbast quotes it per 10 yen, and NerkhAra quotes it per yen; providers normalize all of them to a single-yen price. Toman sources are multiplied by 10 to store Rial internally.
Providers are queried in batches, failures are isolated, and each successful
quote records its source and source URL. Partial results are shown with
warnings on stderr. The cache avoids hammering public endpoints; --watch
intentionally bypasses it.
Exit codes
| Code | Meaning |
|---|---|
0 |
Success (partial provider failures may still exit 0) |
2 |
Usage error, unknown asset, invalid selection |
3 |
Network failure |
4 |
Provider/data failure, no usable prices |
5 |
Invalid configuration |
6 |
Browser failure (reserved; browser errors normally warn) |
130 |
Interrupted with Ctrl+C |
Development
uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
Project layout:
src/chand/
cli/ Typer app, commands, watch/live rendering
core/ models, registry, config, HTTP, cache, pricing service
providers/ one adapter per data source
formatting/ units, Rich tables, JSON, browser helper
test/ offline provider, service, cache, browser, and CLI tests
All tests are offline: HTTP is mocked with recorded payloads, and the browser is stubbed.
Disclaimer
This project is for informational use only. Exchange rates and cryptocurrency prices change rapidly and may differ between sources. Verify data with trusted sources before making financial decisions.
License
Under active development; no license has been finalized yet.
Metadata
Release files for chand 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| chand-0.1.0.tar.gz | 29.1 kB | With provenance | Details for chand-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chand-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for chand-0.1.0-py3-none-any.whl |
Total release size: 72.4 kB
Release files / chand-0.1.0.tar.gz
| Download URL | chand-0.1.0.tar.gz |
|---|---|
| Size | 29.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9de16743a828957f7a4dcc899556f73ce03e0f7d0797cf989c9677d0542c568e
|
|
BLAKE2b-256 checksum How to use checksums |
55c12dcdde15d0ff1a3af789d17bda1d77929c0f6848572d1e9a379beb3907ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / chand-0.1.0-py3-none-any.whl
| Download URL | chand-0.1.0-py3-none-any.whl |
|---|---|
| Size | 43.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6858ad5c002d1387fd156aaa84797f73228823ca026b7a1b82b1cbea1889bf04
|
|
BLAKE2b-256 checksum How to use checksums |
76557ebce9323f8653d11db2a58891d81dd8c6205692dfe89d35392724a75da1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for chand 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for chand-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.