Introduction

Overview

The Hydra API is the gRPC surface of Hydra App — a multi-asset off-chain node spanning Bitcoin (Lightning) and the account-model chains (Lithium on EVM and Tron). Build applications that can:

• Trade across chains — atomic swaps between Bitcoin, Ethereum, Arbitrum, Tron and the tokens on them
• Manage payment channels — open, deposit, withdraw, close, and batch those operations
• Send instant payments — invoices, keysend, and hashlock (HTLC) payments
• Lease liquidity — inbound capacity from the liquidity service, without funding it yourself
• Settle on-chain when there is no channel — on-chain HTLCs as an alternative swap rail
• Follow everything live — streams for balances, channels, payments, markets and swaps

Key Features

Multi-Asset Support

• Bitcoin — native BTC over Lightning
• EVM — the native coin and ERC-20 tokens, over Lithium channels
• Tron — native TRX and TRC-20 tokens
• Cross-chain atomic swaps between any of them

Channel Operations

• Channel lifecycle management, on every protocol
• Payment routing and invoicing
• Direct channel payments
• Hashlock payments (HTLC)

Decentralized Exchange

• Limit and market orders
• Liquidity provision
• Real-time orderbook streaming
• Automated market making

Simple Swaps

• Automatic channel setup
• One-click cross-chain swaps
• Configurable slippage tolerance
• Automatic fund withdrawal

Supported Networks

Mainnet — real funds; access is invite-gated at launch:

Staging — testnet funds only:

Tron is not part of the mainnet launch. The full identifier table, including every other accepted network name, is in the Setup Guide.

API Architecture

Two transports, one port

Hydra App serves gRPC over HTTP/2 and JSON-RPC 2.0 over HTTP on the same settings.server_port, and routes by content type. Browser clients can use gRPC-Web against the same endpoint.

• gRPC — typed, binary, and the only transport that carries the server-streaming subscriptions. Generate stubs from the .proto bundle.
• JSON-RPC — no codegen, ideal for shell scripts and languages without good gRPC tooling. No streaming over plain HTTP POST.

Important: unlike a hosted REST API, you run the server. Hydra App is a node on your own machine or infrastructure; there is no shared endpoint to call, and no API key — see the Setup Guide.

⚠️ The server is unauthenticated — bind it to localhost

Every RPC, including signing, sending and force-closing, is reachable by anyone who can open a TCP connection to the port. Keep it on 127.0.0.1, or behind your own authenticating proxy. Never expose it to a public interface.

Service Organization

The full service list (with RPC counts and per-service doc links) is in Getting Started → Available services.

Real-Time Event Streams

Hydra provides WebSocket-like streaming for real-time updates:

Every event type is catalogued in Events & Subscriptions; how to consume them safely is the Streaming guide.

API Principles

• Resource-oriented. Operations act on channels, orders, payments and assets, named by id.
• Estimate, then execute. Every operation that costs money has an Estimate* twin taking the same request. Call it first — it is also where a simple swap tells you why it cannot proceed.
• Amounts are human-readable. Every DecimalString is in whole asset units — never satoshis, never wei. See Amounts and precision.
• Stateless requests. Each call carries everything it needs; the node holds no per-client session.

⚠️ Most write RPCs are not idempotent

A retry after a timeout can send a second transaction, open a second channel, or place a second order. Get* and Estimate* are always safe; writes need either a verification read first or, for order placement, the client_order_id idempotency token. The rules per RPC are in Errors → Idempotency & Retry Safety.

Rate limits

Hydra App applies no rate limiting — it is your own node, and the only budget that binds is its own capacity and that of the chain endpoints it talks to. A bot that polls where it could subscribe is spending your provider quota, not the API's.

The upstream services the node talks to (orderbook, liquidity service, price oracle) have their own limits, which the node manages on your behalf.

Versioning

The Protocol Buffer package is hydra_app, unversioned: the schema a build speaks is the schema in its bundled rpc.discover output, which is authoritative for that build. Track changes in the Changelog.

Next Steps

1. Getting Started - Make your first API calls
2. Common Patterns - Learn about data structures
3. Wallet API - Check balances and transactions