Search
Search any block height, hash, address (BTC, LTC, BCH, DASH, ETH, TRON), token symbol or contract, or a link from another explorer, and get ranked matches with a type, chain, confidence and reason, plus suggestions on a miss.
# 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).