# Hydration Liquidity Parachain RPC Guide

## Hydration RPC plans and rate limits

- **Free plan:** 20 responses per second, up to 100,000 responses a day.
- **Plans:** $49/mo, $299/mo, $999/mo with 25M, 150M, and 500M included responses. Overages billed at $5/$3/$2 per million responses respectively.
- **Paid rate limits:** 100 to 5,000 responses per second (bursts from 500 to 10,000), no daily limit.
- **Billing:** 1 response = 1 API credit on every shared plan, over HTTPS or WebSocket (WSS) where Hydration supports it.

Details: [Pricing](https://www.dwellir.com/docs/getting-started/pricing) · [Rate limits](https://www.dwellir.com/docs/getting-started/rate-limits) · [Authentication](https://www.dwellir.com/docs/getting-started/authentication) · [Archive nodes](https://www.dwellir.com/docs/getting-started/archive-nodes)

## Why Build on Hydration?

Hydration powers Polkadot's unified liquidity layer, offering deep cross-chain markets through a single omnipool runtime. Teams choose Hydration because it provides:

### **Unified Liquidity Router**

- Route any XCM-enabled asset through the omnipool without fragmented pairs
- Single-sided provisioning with dynamic fee curves tuned for stable markets
- Built-in MEV protection via adaptive liquidity routing

### **Native Cross-Chain Execution**

- Parachain-level integrations with fast finality on the Polkadot Relay Chain
- Out-of-the-box XCM channels to leading parachains for trustless settlement
- Seamless asset teleportation between Hydration and Kusama's Basilisk network

### **Developer-First Tooling**

- Full Substrate JSON-RPC coverage with archive snapshots for historical queries
- Rich analytics via Hydration Subscan and on-chain telemetry feeds
- Reusable SDK patterns across JavaScript, Rust, and Python ecosystems

## Quick Start with Hydration

Connect to Hydration mainnet or Basilisk testnet in seconds using Dwellir-managed infrastructure.

Basilisk mirrors Hydration's runtime for staging releases on Kusama. Use the Basilisk endpoints for pre-production load tests and fee estimation before promoting to Hydration mainnet.

### Installation & Setup

cURL
JavaScript (polkadot.js)
Rust (subxt)
Python (py-substrate-interface)

```bash
curl https://api-hydration.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "chain_getHeader",
    "params": []
  }'
```

**Expected output (2025-10-01):**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "number": "0x904ae4",
    "hash": "0xd2f7f582eb7170b1a6382641a2ad9625cd46cb292fa0a8a1fc6f2bb6e1ed6b4d",
    "parentHash": "0x2f58fc2a2d7024520d2062142c4d7788146101d0736c7c952866adb17bb25483"
  },
  "id": 1
}
```

```typescript
import { ApiPromise, WsProvider } from '@polkadot/api';

async function main() {
  const provider = new WsProvider('wss://api-hydration.n.dwellir.com/YOUR_API_KEY');
  const api = await ApiPromise.create({ provider });

  const [chain, nodeName, version, runtime] = await Promise.all([
    api.rpc.system.chain(),
    api.rpc.system.name(),
    api.rpc.system.version(),
    api.rpc.state.getRuntimeVersion()
  ]);

  console.log(`Connected to ${chain} via ${nodeName} v${version}`);
  console.log(`Runtime specVersion=${runtime.specVersion.toString()}, transactionVersion=${runtime.transactionVersion}`);

  const header = await api.rpc.chain.getHeader();
  console.log(`Latest head #${header.number} (${header.hash.toHex()})`);

  await api.disconnect();
}

main().catch(console.error);
```

```rust
use subxt::{config::substrate::SubstrateConfig, OnlineClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api = OnlineClient::<SubstrateConfig>::from_url(
        "wss://api-hydration.n.dwellir.com/YOUR_API_KEY"
    ).await?;

    let block_hash = api.rpc().block_hash(None).await?.expect("block hash");
    let header = api.rpc().header(Some(block_hash)).await?.expect("header");

    println!("Finalized block #{}", header.number);
    println!("State root {}", header.state_root);

    Ok(())
}
```

```python
from substrateinterface import SubstrateInterface

substrate = SubstrateInterface(
    url="wss://api-hydration.n.dwellir.com/YOUR_API_KEY",
    type_registry_preset="substrate-node-template"
)

chain = substrate.get_chain_head()
print("Latest finalized head:", chain)

runtime = substrate.get_runtime_version()
print("specVersion:", runtime['specVersion'], "transactionVersion:", runtime['transactionVersion'])

account = substrate.query(
    module='System',
    storage_function='Account',
    params=['5FUNjmP7L2nA9dZ1VnoqeY3SFqHZ3MQNrZjSxFv6YWza7yeb']
)
print("Account free balance:", account.value['data']['free'])
```

## Network Information

| Parameter                | Hydration Mainnet                                                    | Basilisk Testnet                                                     |
| ------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Relay Chain**          | Polkadot                                                             | Kusama                                                               |
| **Parachain ID**         | 2034                                                                 | 2090                                                                 |
| **Genesis Hash**         | `0xafdc188f45c71dacbaa0b62e16a91f726c7b8699a9748cdf715459de6b7f366d` | `0xa85cfb9b9fd4d622a5b28289a02347af987d8f73fa3108450e2b4a11c1ce5755` |
| **Runtime (2025-10-01)** | specVersion `347`, transactionVersion `1`                            | specVersion `127`, transactionVersion `1`                            |
| **Unit Symbol**          | HDX                                                                  | BSX                                                                  |
| **Decimals**             | 12                                                                   | 12                                                                   |
| **SS58 Prefix**          | 63                                                                   | 10041                                                                |
| **Explorer**             | hydration.subscan.io                                                 | basilisk.subscan.io                                                  |

### Additional Details

| Parameter              | Value                                       | Details          |
| ---------------------- | ------------------------------------------- | ---------------- |
| Average Block Time     | 6 seconds                                   | GRANDPA finality |
| Native Liquidity Pools | Omnipool, LRNA staking, and routing pallets |                  |

## API Reference

Hydration exposes the full Substrate RPC surface for core operations, staking, governance, liquidity, and runtime-specific `state_call` helpers for omnipool pricing and router analytics.

## Common Integration Patterns

### Real-Time Block Streaming

```typescript
import { ApiPromise, WsProvider } from '@polkadot/api';

const provider = new WsProvider('wss://api-hydration.n.dwellir.com/YOUR_API_KEY');
const api = await ApiPromise.create({ provider });

api.rpc.chain.subscribeNewHeads((header) => {
  console.log(`New Hydration block #${header.number.toString()} (${header.hash.toHex()})`);
});
```

### Query Treasury Balances via Raw Storage

```bash
curl https://api-hydration.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "state_getStorage",
    "params": [
      "0x26aa394eea5630e07c48ae0c9558cef7b6a7c9a35a95a160cb4cad330558dfa56d6f646c755b98a7afd0913860592153322b957be394a0619f20b32679ac1014"
    ]
  }'
```

The key above targets `System.Account` for `5EYCAe5jiUusQ3yAkVAP1YF81oXasuAHt2KG8Xjc433Zbx8A` (Hydration treasury). Decode the SCALE response to obtain the 6,952,142,503,371.701702601733 HDX free balance observed on 2025-10-01.

### Batch Weight and Fee Simulation

```typescript
const api = await ApiPromise.create({ provider: new WsProvider('wss://api-hydration.n.dwellir.com/YOUR_API_KEY') });

const tx = api.tx.omnipool.sell(
  assetInId,
  assetOutId,
  amountIn,
  minimumReceived
);

const info = await api.rpc.payment.queryInfo(tx.toHex());
console.log(`Estimated fee: ${info.partialFee.toHuman()}`);
console.log(`Weight: ${info.weight.toString()} refTime`);
```

## Performance Best Practices

- Prefer WebSocket endpoints for subscriptions (`chain_subscribeNewHeads`, `grandpa_subscribeJustifications`).
- Cache runtime metadata and type registries keyed by `specVersion` (`347` as of 2025-10-01) to avoid repeated handshakes.
- Use `state_getKeysPaged` with `pageSize <= 1000` when scanning omnipool storage to prevent heavy RPC loads.
- Rate-limit bulk extrinsic submissions and enable exponential backoff on `author_submitExtrinsic` errors.
- Pin queries to finalized block hashes whenever you need deterministic historical data.

## Troubleshooting

| Symptom                          | Likely Cause                            | Resolution                                                               |
| -------------------------------- | --------------------------------------- | ------------------------------------------------------------------------ |
| `API key does not exist`         | Missing or mis-typed Dwellir key        | Re-issue credentials via the Dwellir dashboard and update endpoint URLs  |
| `1010: Invalid Transaction`      | Runtime version drift or outdated nonce | Re-fetch metadata, synchronize account nonce, and rebuild the payload    |
| Null `state_getStorage` response | Storage key mismatch                    | Recompute the key with `blake2_128_concat` of the SS58-decoded AccountId |
| WebSocket disconnects after idle | Inactive ping/pong                      | Enable keep-alive heartbeats every 20 seconds and auto-retry with jitter |

## FAQs

**Does Hydration support archive queries?**
Yes. Dwellir retains full historical state so you can request old block hashes, query omnipool states, and reconstruct trades for compliance.

**What SS58 prefix should wallets use?**
Hydration uses prefix `63`. Basilisk uses `10041`. Ensure address derivation matches the target environment.

**How do I estimate swap slippage programmatically?**
Fetch omnipool reserves via `state_call` (custom RPC `OmnipoolApi_quotePrice`) and pair it with `payment_queryInfo` estimates to account for weight-based fees.

## Smoke Tests

Run these checks before deploying to production:

1. **Node health**
   ```bash
   curl https://api-hydration.n.dwellir.com/YOUR_API_KEY \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"system_health","params":[]}'
   ```
   Expect peers ≥ 8 and `isSyncing: false`.

2. **Latest header**
   ```bash
   curl https://api-hydration.n.dwellir.com/YOUR_API_KEY \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":2,"method":"chain_getHeader","params":[]}'
   ```
   Confirm block numbers advance roughly every 6 seconds.

3. **Account snapshot**
   ```bash
   curl https://api-hydration.n.dwellir.com/YOUR_API_KEY \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":3,"method":"state_getStorage","params":["0x26aa394eea5630e07c48ae0c9558cef7b6a7c9a35a95a160cb4cad330558dfa56d6f646c755b98a7afd0913860592153322b957be394a0619f20b32679ac1014"]}'
   ```
   Decode the SCALE payload and verify balances.

## Migration Guide (Polkadot → Hydration)

- **Update endpoints:** Replace legacy Polkadot URLs with `https://api-hydration.n.dwellir.com/YOUR_API_KEY` or the Basilisk staging endpoint.
- **Adjust address encoding:** Switch wallet and service configurations to SS58 prefix `63`. Existing Polkadot addresses (prefix `0`) must be re-derived.
- **Refresh metadata:** Download the latest metadata (`specVersion 347`) and update custom type bundles for omnipool-related pallets.
- **Re-evaluate fees:** Run `payment_queryInfo` against Hydration extrinsics. Weights differ from Polkadot because of liquidity logic.
- **Review pallet availability:** Hydration includes omnipool, router, and incentive pallets not present on Polkadot; ensure you check `rpc_methods` for the namespaces you rely on.

## Resources & Tools

- [Hydration node releases](https://github.com/galacticcouncil/HydraDX-node/releases): runtime changelogs and spec version history
- [Polkadot.js Apps explorer](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Fapi-hydration.n.dwellir.com%2FYOUR_API_KEY#/explorer): browser-based console
- [Hydration runtime configuration source](https://github.com/galacticcouncil/hydration-node/blob/master/node/res/hydradx.json): chain specification in the node repository
- [Dwellir Dashboard](https://dashboard.dwellir.com/register): get your API key

Ready to launch? Deploy with Hydration's omnipool liquidity and monitor production traffic through Dwellir's analytics.