# Olenza API documentation

The same content as https://olenza.io/docs, as markdown. Machine-readable descriptions: https://node.olenza.io/openapi.json (Node) and https://explorer.olenza.io/api/openapi.json (Explorer API).

# Olenza Node — JSON-RPC

Direct JSON-RPC to our own full nodes for every chain. No node to run yourself.

## Endpoint

```
POST https://node.olenza.io/v1/rpc/{chain}
```

Chains: `btc`, `eth`, `ltc`, `doge`, `bch`, `xec`, `zec`, `dcr`, `xmr`. The body is a standard JSON-RPC request, or an array of them for a batch.

## Authentication

Send your API key in a header:

```
X-API-Key: olz_…
Authorization: Bearer olz_…     (either one)
```

If your client cannot set headers, put the key in the path: `https://node.olenza.io/v1/rpc/{chain}/olz_…`. Prefer the header: our servers never log the path or the full key, but your own tools, proxies and browser history may keep a URL. The same key works for the Explorer API (header only there).

## Examples

Each chain speaks its own node's dialect — the gateway does not translate. One example per dialect:

**Bitcoin-style RPC** — BTC, LTC, DOGE, BCH, XEC, ZEC, DCR

```
curl https://node.olenza.io/v1/rpc/btc \
  -H "X-API-Key: $OLENZA_KEY" \
  --data '{"jsonrpc":"1.0","id":1,"method":"getblockcount","params":[]}'
```

Example response:

```
{"result":969857,"error":null,"id":1}
```

**Ethereum JSON-RPC** — ETH

```
curl https://node.olenza.io/v1/rpc/eth \
  -H "X-API-Key: $OLENZA_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

Example response:

```
{"jsonrpc":"2.0","id":1,"result":"0x18e8d0f"}
```

**Monero daemon RPC** — XMR

```
curl https://node.olenza.io/v1/rpc/xmr \
  -H "X-API-Key: $OLENZA_KEY" \
  --data '{"jsonrpc":"2.0","id":"0","method":"get_block_count"}'
```

Example response:

```
{"id":"0","jsonrpc":"2.0","result":{"count":3776747,"status":"OK","untrusted":false}}
```

Opening an endpoint in a browser shows a short help page; a `GET` from code is refused with `405 USE_POST`.

## Limits and headers

Once your key is recognised, every response — answers and refusals alike — carries your current limits. Refusals before that (`401`, an unknown chain, `TOO_MANY_INVALID_KEYS`) do not.

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Burst size of your plan |
| `X-RateLimit-Remaining` | Requests you can send right now |
| `X-RateLimit-Reset` | Seconds until the burst is fully refilled (not a timestamp) |
| `X-Quota-Daily-Remaining` | Units left today (UTC) |
| `X-Quota-Monthly-Remaining` | Units left this month (UTC) |
| `X-Quota-Key-Daily-Remaining` | Units left today on this key, when you set a per-key daily cap |
| `X-Request-Id` | A unique id for this request, on every response — quote it if you contact support (support@olenza.io) |

## Errors

Errors are JSON-RPC error objects. `error.data.reason` is a stable code:

| HTTP | Reason | What to do |
|---|---|---|
| 401 | `MISSING_API_KEY`, `INVALID_API_KEY` | Check the key |
| 403 | `KEY_REVOKED` | The key was revoked — create a new one |
| 403 | `ACCOUNT_SUSPENDED` | Email support@olenza.io with your account email and the `X-Request-Id` of a failed call |
| 403 | `CHAIN_NOT_IN_PLAN`, `PLAN_UNAVAILABLE` | Your plan does not cover this — upgrade or contact support |
| 403 | `METHOD_NOT_ALLOWED` | The method is not available — see the list below |
| 404 | `CHAIN_NOT_FOUND` | Check the chain in the URL |
| 405 | `USE_POST` | The endpoint was called with `GET` — send a `POST` with a JSON-RPC body |
| 400 | `INVALID_REQUEST`, `BATCH_TOO_LARGE`, `INVALID_PARAMS` | Fix the request |
| 400 | `RANGE_TOO_LARGE` | Ask for a smaller range and page through it (at most 10,000 blocks for `eth_getLogs`, 1,000 for Monero header ranges; on Decred 100 blocks or 10 windows for `ticketfeeinfo`/`txfeeinfo`, a 1,440-block `txfeeinfo` range, 10,000 for `ticketvwap`) |
| 413 | `REQUEST_TOO_LARGE` | Send a smaller request |
| 429 | `RATE_LIMITED` | Wait `Retry-After` seconds |
| 429 | `TOO_MANY_CONCURRENT` | Too many of your calls are running at once — wait for one to finish |
| 429 | `TOO_MANY_INVALID_KEYS` | Too many unknown keys from your address — fix the key, then wait `Retry-After` seconds |
| 429 | `DAILY_QUOTA_EXCEEDED`, `MONTHLY_QUOTA_EXCEEDED`, `KEY_DAILY_QUOTA_EXCEEDED` | Wait for the next UTC day/month, or upgrade |
| 502 | `NODE_ERROR` | Retry shortly; not charged, unless the call ran past the time limit |
| 502 | `RESPONSE_TOO_LARGE` | The answer is over 64 MB — ask for less; charged, since the node did the work |
| 503 | `NODE_BUSY`, `NODE_SYNCING`, `NODE_UNAVAILABLE`, `SERVICE_UNAVAILABLE` | Retry shortly; not charged |
| 503 | `GATEWAY_BUSY` | We are at capacity — wait `Retry-After` seconds. Not charged, unless the answer had already passed 1 MB |

Errors returned by the node itself (for example "Block not found") are passed through unchanged.

Using the API means accepting the Terms of Service (https://olenza.io/terms) — in short: one free account per person, no reselling raw access, no getting around limits.

## Available methods

Only these methods are available — wallet, peer, node-control and UTXO-set scan methods are not. Every call counts as one unit.

### BTC — Bitcoin

bitcoin dialect · 45 methods · page: https://node.olenza.io/btc

`analyzepsbt`, `combinepsbt`, `combinerawtransaction`, `converttopsbt`, `createmultisig`, `createpsbt`, `createrawtransaction`, `decodepsbt`, `decoderawtransaction`, `decodescript`, `deriveaddresses`, `estimatesmartfee`, `finalizepsbt`, `getbestblockhash`, `getblock`, `getblockchaininfo`, `getblockcount`, `getblockhash`, `getblockheader`, `getblockstats`, `getchaintips`, `getchaintxstats`, `getdeploymentinfo`, `getdescriptorinfo`, `getdifficulty`, `getindexinfo`, `getmempoolancestors`, `getmempooldescendants`, `getmempoolentry`, `getmempoolinfo`, `getmininginfo`, `getnetworkhashps`, `getrawmempool`, `getrawtransaction`, `gettxout`, `gettxoutproof`, `gettxspendingprevout`, `joinpsbts`, `sendrawtransaction`, `submitpackage`, `testmempoolaccept`, `utxoupdatepsbt`, `validateaddress`, `verifymessage`, `verifytxoutproof`

### ETH — Ethereum

ethereum dialect · 35 methods · Ethereum JSON-RPC 2.0 on an Erigon archive node: state and traces are available at any height. eth_getLogs covers at most 10,000 blocks per call; trace_* on old blocks is slow. · page: https://node.olenza.io/eth

`eth_blockNumber`, `eth_call`, `eth_chainId`, `eth_createAccessList`, `eth_estimateGas`, `eth_feeHistory`, `eth_gasPrice`, `eth_getBalance`, `eth_getBlockByHash`, `eth_getBlockByNumber`, `eth_getBlockReceipts`, `eth_getBlockTransactionCountByHash`, `eth_getBlockTransactionCountByNumber`, `eth_getCode`, `eth_getLogs`, `eth_getProof`, `eth_getStorageAt`, `eth_getTransactionByBlockHashAndIndex`, `eth_getTransactionByBlockNumberAndIndex`, `eth_getTransactionByHash`, `eth_getTransactionCount`, `eth_getTransactionReceipt`, `eth_getUncleByBlockNumberAndIndex`, `eth_getUncleCountByBlockHash`, `eth_getUncleCountByBlockNumber`, `eth_maxPriorityFeePerGas`, `eth_sendRawTransaction`, `eth_syncing`, `net_listening`, `net_version`, `trace_block`, `trace_call`, `trace_transaction`, `txpool_status`, `web3_clientVersion`

### LTC — Litecoin

bitcoin dialect · 42 methods · page: https://node.olenza.io/ltc

`analyzepsbt`, `combinepsbt`, `combinerawtransaction`, `converttopsbt`, `createmultisig`, `createpsbt`, `createrawtransaction`, `decodepsbt`, `decoderawtransaction`, `decodescript`, `deriveaddresses`, `estimatesmartfee`, `finalizepsbt`, `getbestblockhash`, `getblock`, `getblockchaininfo`, `getblockcount`, `getblockhash`, `getblockheader`, `getblockstats`, `getchaintips`, `getchaintxstats`, `getdescriptorinfo`, `getdifficulty`, `getindexinfo`, `getmempoolancestors`, `getmempooldescendants`, `getmempoolentry`, `getmempoolinfo`, `getmininginfo`, `getnetworkhashps`, `getrawmempool`, `getrawtransaction`, `gettxout`, `gettxoutproof`, `joinpsbts`, `sendrawtransaction`, `testmempoolaccept`, `utxoupdatepsbt`, `validateaddress`, `verifymessage`, `verifytxoutproof`

### DOGE — Dogecoin

bitcoin dialect · 28 methods · Dogecoin Core 1.14 is an older Bitcoin Core branch: no PSBT and no testmempoolaccept. · page: https://node.olenza.io/doge

`createmultisig`, `createrawtransaction`, `decoderawtransaction`, `decodescript`, `estimatesmartfee`, `getbestblockhash`, `getblock`, `getblockchaininfo`, `getblockcount`, `getblockhash`, `getblockheader`, `getblockstats`, `getchaintips`, `getdifficulty`, `getmempoolancestors`, `getmempooldescendants`, `getmempoolentry`, `getmempoolinfo`, `getmininginfo`, `getnetworkhashps`, `getrawmempool`, `getrawtransaction`, `gettxout`, `gettxoutproof`, `sendrawtransaction`, `validateaddress`, `verifymessage`, `verifytxoutproof`

### BCH — Bitcoin Cash

bitcoin dialect · 37 methods · BCHN. estimatesmartfee does not exist; use estimatefee. · page: https://node.olenza.io/bch

`combinepsbt`, `combinerawtransaction`, `converttopsbt`, `createmultisig`, `createpsbt`, `createrawtransaction`, `decodepsbt`, `decoderawtransaction`, `decodescript`, `estimatefee`, `finalizepsbt`, `getbestblockhash`, `getblock`, `getblockchaininfo`, `getblockcount`, `getblockhash`, `getblockheader`, `getblockstats`, `getchaintips`, `getchaintxstats`, `getdifficulty`, `getindexinfo`, `getmempoolancestors`, `getmempooldescendants`, `getmempoolentry`, `getmempoolinfo`, `getmininginfo`, `getnetworkhashps`, `getrawmempool`, `getrawtransaction`, `gettxout`, `gettxoutproof`, `sendrawtransaction`, `testmempoolaccept`, `validateaddress`, `verifymessage`, `verifytxoutproof`

### XEC — eCash

bitcoin dialect · 43 methods · 1 XEC = 100 satoshi (2 decimals), unlike Bitcoin's 8. · page: https://node.olenza.io/xec

`analyzepsbt`, `combinepsbt`, `combinerawtransaction`, `converttopsbt`, `createmultisig`, `createpsbt`, `createrawtransaction`, `decodepsbt`, `decoderawtransaction`, `decodescript`, `deriveaddresses`, `estimatefee`, `finalizepsbt`, `getbestblockhash`, `getblock`, `getblockchaininfo`, `getblockcount`, `getblockhash`, `getblockheader`, `getblockstats`, `getchaintips`, `getchaintxstats`, `getdescriptorinfo`, `getdifficulty`, `getindexinfo`, `getmempoolancestors`, `getmempooldescendants`, `getmempoolentry`, `getmempoolinfo`, `getmininginfo`, `getnetworkhashps`, `getrawmempool`, `getrawtransaction`, `gettxout`, `gettxoutproof`, `joinpsbts`, `sendrawtransaction`, `submitpackage`, `testmempoolaccept`, `utxoupdatepsbt`, `validateaddress`, `verifymessage`, `verifytxoutproof`

### ZEC — Zcash

bitcoin dialect · 19 methods · zebrad speaks the Bitcoin dialect. Transparent (t-) addresses only: shielded balances are private by design. getaddresstxids on a busy address is slow; at most 16 addresses per call. · page: https://node.olenza.io/zec

`estimatefee`, `getaddressbalance`, `getaddresstxids`, `getaddressutxos`, `getbestblockhash`, `getblock`, `getblockchaininfo`, `getblockcount`, `getblockhash`, `getblockheader`, `getblocksubsidy`, `getdifficulty`, `getmininginfo`, `getnetworksolps`, `getrawmempool`, `getrawtransaction`, `sendrawtransaction`, `validateaddress`, `z_validateaddress`

### DCR — Decred

bitcoin dialect · 47 methods · dcrd, the Bitcoin dialect plus Decred's staking calls (tickets, votes, treasury). No address history index: use existsaddress or ticketsforaddress. · page: https://node.olenza.io/dcr

`createrawtransaction`, `decoderawtransaction`, `decodescript`, `estimatefee`, `estimatesmartfee`, `estimatestakediff`, `existsaddress`, `existsaddresses`, `existsliveticket`, `existslivetickets`, `existsmempooltxs`, `getbestblock`, `getbestblockhash`, `getblock`, `getblockchaininfo`, `getblockcount`, `getblockhash`, `getblockheader`, `getblocksubsidy`, `getcfilterv2`, `getchaintips`, `getcoinsupply`, `getcurrentnet`, `getdifficulty`, `getheaders`, `getmempoolinfo`, `getmininginfo`, `getnetworkhashps`, `getrawmempool`, `getrawtransaction`, `getstakedifficulty`, `getstakeversioninfo`, `getstakeversions`, `getticketpoolvalue`, `gettreasurybalance`, `gettreasuryspendvotes`, `gettxout`, `getvoteinfo`, `livetickets`, `sendrawtransaction`, `ticketfeeinfo`, `ticketsforaddress`, `ticketvwap`, `txfeeinfo`, `validateaddress`, `verifymessage`, `version`

### XMR — Monero

monero dialect · 17 methods · monerod JSON-RPC. Only /json_rpc methods are available; monerod's separate binary endpoints (/get_outs, /getblocks.bin) are not, so a light wallet cannot sync through this route. · page: https://node.olenza.io/xmr

`get_alternate_chains`, `get_block`, `get_block_count`, `get_block_header_by_hash`, `get_block_header_by_height`, `get_block_headers_range`, `get_coinbase_tx_sum`, `get_fee_estimate`, `get_info`, `get_last_block_header`, `get_miner_data`, `get_output_distribution`, `get_output_histogram`, `get_txpool_backlog`, `get_version`, `hard_fork_info`, `on_get_block_hash`

# Olenza Explorer — REST

Blocks, transactions and addresses as JSON, from the same indexes as the explorer site (https://explorer.olenza.io/).

## Endpoint

```
GET https://explorer.olenza.io/api/v1/{chain}/…
```

Chains: `btc`, `eth`, `ltc`, `doge`, `bch`, `xec`, `zec`, `dcr`, `xmr`. `GET`, except the one endpoint that takes a secret (`outputs/check`, a `POST`); answers are `application/json`.

## Authentication

Send your API key in the `X-API-Key` header (or `Authorization: Bearer`). The same key works for Olenza Node. Keys are never accepted in the URL — URLs end up in logs.

```
curl -H "X-API-Key: $OLENZA_KEY" https://explorer.olenza.io/api/v1/btc/status
```

## Chains do not all work the same way

A Bitcoin transaction consumes outputs and creates new ones. An Ethereum transaction is one account calling another. A Monero transaction hides its amounts and recipients on purpose. So the API has three shapes and `/status` says which one a chain answers with, in `family`:

| `family` | Chains | What a transaction looks like | Addresses |
|---|---|---|---|
| `utxo` | btc ltc doge bch xec zec dcr | Inputs and outputs, each with an amount and addresses | Balance, history, unspent outputs |
| `account` | eth | Sender, recipient, value and gas, plus the logs, internal operations and token transfers the receipt shows | Balance, nonce, code, history by cursor |
| `ring` | xmr | Key images, the ring each input hides in, one-time output keys. Amounts appear only where the protocol makes them public | None. A Monero address never appears on the chain |

An endpoint a chain's family does not have answers `404 NOT_ON_THIS_CHAIN` and says why.

## Basics

- Amounts are strings in the coin's smallest unit. Divide by 10^decimals — `decimals` is in `/status`.
- A field that does not apply to a chain is left out, never `null`.
- Paging: `page` and `page_size` where a chain has stable pages; `cursor` and `limit` on account chains (the next cursor comes back in the answer).

## Plans, limits and errors

Every call counts as one unit, whatever the endpoint, and once against the per-second rate limit. The Explorer API has its own plan and allowance, separate from Olenza Node. Every response carries the same `X-RateLimit-*`, `X-Quota-*` and `X-Request-Id` headers as Node. 5xx the explorer fails to answer are not charged, except `504 UPSTREAM_TIMEOUT`, which is charged like any call that runs past the time limit; a `404` for something that does not exist is an answer and is charged.

```
{"error": {"reason": "NOT_FOUND", "message": "transaction not found"}}
```

| HTTP | reason | Meaning |
|---|---|---|
| 400 | `BAD_REQUEST` | Malformed height, hash, address or parameter. |
| 401 | `MISSING_API_KEY`, `INVALID_API_KEY` | No key, or not a valid key. |
| 403 | `KEY_REVOKED`, `ACCOUNT_SUSPENDED`, `CHAIN_NOT_IN_PLAN` | The key or account cannot use this. |
| 404 | `NOT_FOUND` | No such block, transaction or address. |
| 404 | `CHAIN_NOT_FOUND`, `ENDPOINT_NOT_FOUND` | Unknown chain or path. |
| 404 | `NOT_ON_THIS_CHAIN` | This chain's family has no such thing. |
| 429 | `RATE_LIMITED`, `DAILY_QUOTA_EXCEEDED`, `MONTHLY_QUOTA_EXCEEDED`, `KEY_DAILY_QUOTA_EXCEEDED`, `TOO_MANY_CONCURRENT`, `TOO_MANY_INVALID_KEYS` | Slow down; `Retry-After` says for how long. |
| 503 | `GATEWAY_BUSY` | We are at capacity; retry after `Retry-After` seconds. |
| 502, 503, 504 | `UPSTREAM_ERROR`, `SERVICE_UNAVAILABLE`, `UPSTREAM_TIMEOUT` | Our side; not charged unless the call ran past the time limit. Retry shortly. |

## Endpoints

Base `https://explorer.olenza.io/api/v1/{chain}/…`. Which endpoints a chain answers depends on its `family`. Per-chain reference with live sample answers: https://explorer.olenza.io/api/{chain}.

Every chain:

| Endpoint | Returns |
|---|---|
| `GET /{chain}/status` | Chain tip, sync state, symbol, decimals, mempool size, and `family`. |
| `GET /{chain}/blocks` | Latest blocks, newest first (`limit`, `start`). |
| `GET /{chain}/block/{height\|hash}` | One block's header and transaction count. |
| `GET /{chain}/block/{height\|hash}/txs` | A block's transactions. |
| `GET /{chain}/tx/{hash}` | One transaction, in the chain family's shape. |
| `GET /{chain}/mempool` | Transactions waiting to be mined. |
| `GET /{chain}/search/{query}` | What a height, hash or address is. |

`utxo` chains:

| Endpoint | Returns |
|---|---|
| `GET /{chain}/address/{address}` | Balance, total received and sent, transaction count. |
| `GET /{chain}/address/{address}/txs` | An address's transactions, newest first. |
| `GET /{chain}/address/{address}/utxo` | Unspent outputs (largest first; at most 1000, with a count). |

`account` chains (Ethereum):

| Endpoint | Returns |
|---|---|
| `GET /{chain}/address/{address}` | Balance in wei, nonce, and whether it holds code. |
| `GET /{chain}/address/{address}/txs` | An address's transactions by cursor, with `coverage`. |
| `GET /{chain}/gas` | Current base fee and priority-fee suggestions. |
| `GET /{chain}/contract/{address}` | Who created a contract, and in which transaction. |

`ring` chains (Monero):

| Endpoint | Returns |
|---|---|
| `POST /{chain}/tx/{hash}/outputs/check` | Which outputs of a transaction belong to an address — you supply a `viewkey` or `txkey`. POST so the key stays out of logs; nothing is stored. |

Monero has no address lookup: an address never appears on the chain.