Introduction
Overview
Hydra API provides programmatic access to a multi-asset Lightning Network implementation. Build applications that can:
- Trade across chains - Swap between Bitcoin, Ethereum, and other assets
- Manage Lightning channels - Open, close, deposit, and withdraw from payment channels
- Send instant payments - Route payments across the Lightning Network
- Rent liquidity - Access inbound liquidity without managing channels
- Access real-time data - Subscribe to market events and orderbook updates
Key Features
Multi-Asset Support
- Bitcoin (native and RGB assets)
- Ethereum (ETH and ERC20 tokens)
- Cross-chain atomic swaps
Lightning Network Operations
- Channel lifecycle management
- 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
| Network | Protocol | Network ID | Native Asset |
|---|---|---|---|
| Bitcoin Signet | 0 (BITCOIN) | 0a03cf40 | Native BTC |
| Ethereum Sepolia | 1 (EVM) | 11155111 | 0x0000000000000000000000000000000000000000 |
| Arbitrum Sepolia | 1 (EVM) | 421614 | 0x0000000000000000000000000000000000000000 |
API Architecture
gRPC-Web Protocol
Hydra uses gRPC-Web with Protocol Buffers for efficient, type-safe communication.
Important: Unlike REST APIs, you need to run the Hydra app server locally or on your infrastructure.
Benefits:
- Binary protocol for faster transmission
- Strongly-typed schema
- Bidirectional streaming support
- Built-in code generation
- Self-hosted - full control over your infrastructure
Service Organization
| Service | Purpose |
|---|---|
| AppService | Network info, general operations, invites/referral, archive retention |
| WalletService | Balance queries and transaction history |
| OrderbookService | Trading, market data, and real-time events |
| SwapService | Swap estimation, execution, and progress tracking |
| NodeService | Channel and payment management |
| PreimageService | Settle a revealed preimage across channel + on-chain legs |
| HtlcService | On-chain HTLC settlement (lock / claim / refund / verify) |
| LiquidityService | Service-backed channel liquidity (the Lease API) |
| PricingService | Asset price feeds |
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:
| Stream | Purpose |
|---|---|
| SubscribeMarketEvents | Public market data, orderbook, trades, candlesticks |
| SubscribeDEXEvents | Personal trading activity, orders, balances, swaps |
| SubscribeSimpleSwaps | Simple swap progress with automatic channel setup |
| SubscribeHtlcEvents | On-chain HTLC lifecycle (locked / claimed / refunded) |
API Principles
RESTful Concepts
While using gRPC, Hydra follows REST principles:
- Resource-oriented - Operations act on resources (channels, orders, payments)
- Idempotent operations - Safe to retry most operations
- Stateless - Each request contains all necessary information
Request/Response Pattern
Most operations follow a request-response pattern:
Request → [Validation] → [Execution] → Response
Streaming Endpoints
Some endpoints provide real-time updates:
SubscribeMarketEvents- Market updatesSubscribeDEXEvents- All trading eventsSubscribeSimpleSwaps- Swap progress updates
Rate Limits
(To be determined based on deployment)
Current recommendation: Limit requests to 1200/minute per IP address.
Versioning
API version is embedded in the Protocol Buffer package: hydra_app
Breaking changes will be announced 30 days in advance.
Next Steps
- Getting Started - Make your first API calls
- Common Patterns - Learn about data structures
- Wallet API - Check balances and transactions