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

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

Real-Time Event Streams

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

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 updates
• SubscribeDEXEvents - All trading events
• SubscribeSimpleSwaps - 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

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