# JSON-RPC over HTTP

Send standard JSON-RPC 2.0 requests to blockchain nodes through a single HTTPS endpoint. The chain lives in the URL path; everything else is the node's native JSON-RPC.

POST `rpc.vilna.io/{chain}`
JSON-RPC 2.0
EVM · Solana · Bitcoin
`X-Api-Key` header

## Request format 

```
POST https://rpc.vilna.io/{chain}
```

`{chain}` is a CAIP-2 ID or network alias; see [supported networks](/apis/rpc#supported-networks). EVM, Bitcoin and Solana use JSON-RPC; Solana also accepts `solana:mainnet` and `solana:testnet`. Tron uses [gRPC](/apis/rpc/grpc).

| Parameter | Value |
|  --- | --- |
| Content-Type | `application/json` |
| Authentication | `X-Api-Key` header |
| Request body limit, configurable default | 1,048,576 bytes (1 MiB) |
| Request timeout, configurable default | 30 seconds |


## Examples 

Pick a chain - each accepts its node's native methods, by alias or RPC routing identifier.

Ethereum

EVM chains - eth_* methods

alias: ethereum

By alias

```bash
curl -X POST https://rpc.vilna.io/ethereum \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 }'
```

By CAIP-2 ID

```bash
curl -X POST https://rpc.vilna.io/eip155:1 \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 }'
```

Every EVM-compatible chain (Ethereum, BSC, Polygon, Avalanche, Arbitrum, Optimism, Base, …) shares the same [Ethereum JSON-RPC methods](https://ethereum.org/en/developers/docs/apis/json-rpc/).

Solana

Native Solana JSON-RPC

alias: solana

By alias

```bash
curl -X POST https://rpc.vilna.io/solana \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "getBalance", "params": ["83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri"], "id": 1 }'
```

By RPC identifier

```bash
curl -X POST https://rpc.vilna.io/solana:mainnet \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "getBalance", "params": ["83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri"], "id": 1 }'
```

Solana exposes its native [JSON-RPC API methods](https://solana.com/docs/rpc).

Bitcoin

Bitcoin Core JSON-RPC

alias: bitcoin

By alias

```bash
curl -X POST https://rpc.vilna.io/bitcoin \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "getblockcount", "params": [], "id": 1 }'
```

By CAIP-2 ID

```bash
curl -X POST https://rpc.vilna.io/bip122:000000000019d6689c085ae165831e93 \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "getblockcount", "params": [], "id": 1 }'
```

Bitcoin supports the standard [Bitcoin Core JSON-RPC methods](https://developer.bitcoin.org/reference/rpc/).

## Error handling 

For an uncertain transaction broadcast, follow the [recovery steps before retrying](/apis/rpc#retries).

Access failures and proxy failures have different formats.

**Authentication and access errors** use [problem+json](/apis/errors). For example, a missing or invalid key returns:

```json
{
  "type": "https://docs.vilna.io/apis/errors#unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "auth.unauthorized",
  "detail": "Invalid or missing credentials"
}
```

**Proxy errors** use JSON-RPC 2.0 with `data.source: vilna`:

```json
{ "jsonrpc": "2.0", "error": { "code": -32001, "message": "chain not found", "data": { "source": "vilna" } }, "id": null }
```

| Situation | HTTP status | Format |
|  --- | --- | --- |
| Missing or invalid key | `401` | problem+json |
| Wrong key type or insufficient permission | `403` | problem+json |
| Network not found | `404` | JSON-RPC, `-32001` |
| Upstream connection failure | `502` | JSON-RPC, `-32003`, `bad gateway` |
| Upstream service unavailable | `503` | JSON-RPC, `-32003`, `service unavailable` |
| Upstream response timeout | `504` | JSON-RPC, `-32003`, `gateway timeout` |
| Request rate limit exceeded | `429` | JSON-RPC, `-32005`, `rate limit exceeded` |


Access failures and timeouts before the request reaches a node can return problem+json; the format depends on where the request fails. See [Errors](/apis/errors).

**Node errors** come straight from the blockchain node in its native [JSON-RPC 2.0 error](https://www.jsonrpc.org/specification#error_object) shape:

```json
{
  "jsonrpc": "2.0",
  "error": { "code": -32601, "message": "Method not found" },
  "id": 1
}
```