Api

Setup Guide

Install and run Hydranet App with Docker Compose

This guide will help you set up and connect to the Hydranet API.

Prerequisites

  • Docker & Docker Compose
  • Node.js 18+ (for client applications)

Overview

The Hydranet API uses gRPC-Web for communication, which means you need to run the Hydranet App server that exposes the gRPC services. Unlike traditional REST APIs, you cannot simply make HTTP requests - you need to use gRPC clients.

Architecture:

Your Application (gRPC-Web Client)
          ↓
    gRPC-Web Protocol
          ↓
Hydranet App Server (localhost:5001 or your hosted server)
          ↓
    ├─ Orderbook/Hub
    ├─ Testnet Networks (Bitcoin Signet, Ethereum Sepolia, Arbitrum Sepolia)
    └─ Data Storage

Step 1: Set Up Hydranet App with Docker

The Hydranet App runs as a Docker container with built-in gRPC-Web support.

Docker Image

ghcr.io/offchain-dex/hydra-app:testnet

1. Create Configuration Directory

Create a docker/ directory for your configuration files:

mkdir docker
cd docker

2. Create Configuration Files

docker/config.yaml - Network configuration for testnet networks:

Create a config.yaml file with your network settings. Example configuration for Bitcoin Signet, Ethereum Sepolia, and Arbitrum Sepolia:

settings:
  data_path_name: hydra-app
  server_port: 5001

authentication_config:
  auth_grpc_url: https://authentication-service-grpc.hydranet.ai
  auth_ws_url: wss://authentication-service-ws.hydranet.ai

backup_config:
  grpc_url: https://backup-service.hydranet.ai

rental_config:
  rental_url: https://rental-manager.hydranet.ai

orderbook_config:
  orderbook_url: https://order-book.hydranet.ai

data_config:
  data_provider_url: https://hydra-proxy.hydranet.ai
  fiat_currencies:
    - USD

networks:
  - protocol: bitcoin
    network: bitcoin-signet
    esplora_url: https://hydra-proxy.hydranet.ai/esplora/signet
    lightning_tcp_port: 19735
    gossip_sync:
      type: rgs
      rgs_server_url: https://rgs.mutinynet.com

  - protocol: evm
    network: ethereum-sepolia
    web3_provider_url: wss://rpc-proxy.hydranet.ai/web3/ws/11155111
    etherscan_url: https://hydra-proxy.hydranet.ai/etherscan
    lithium_http_subgraph_url: https://subquery.hydranet.ai/ethereum
    lithium_ws_subgraph_url: wss://subquery.hydranet.ai/ethereum
    lithium_contract_address: "0x7798f5AE9935d83a7863F5daE8658207BE67CAE9"
    lithium_ws_port: 29981
    watchtower: true
    tokens:
      - "ERC20:0x8cd0dA3d001b013336918b8Bc4e56D9DDa1347E0" # USDC

  - protocol: evm
    network: arbitrum-sepolia
    web3_provider_url: wss://rpc-proxy.hydranet.ai/web3/ws/421614
    etherscan_url: https://hydra-proxy.hydranet.ai/etherscan
    lithium_http_subgraph_url: https://subquery.hydranet.ai/arbitrum
    lithium_ws_subgraph_url: wss://subquery.hydranet.ai/arbitrum
    lithium_contract_address: "0x6adf0729f477681E1869d9BFD84816BBcEe69010"
    lithium_ws_port: 29982
    watchtower: true
    tokens:
      - "ERC20:0x67E6a7eaE40107FF676908B28C3FC632A38f1499" # HDN

docker/.env - Environment configuration:

Create a .env file with the following settings:

RUST_LOG="none"
MNEMONIC=""        # Optional: See "Mode Selection" below
PASSWORD=""        # Optional: Encryption password for daemon mode
GRPC_PORT=5001
DATA_PATH_NAME=hydra-app

Mode Selection:

The Hydranet App operates in two modes based on the MNEMONIC environment variable:

  • Interactive Mode (No MNEMONIC set):
    • Leave MNEMONIC="" (empty)
    • Allows manual wallet management via CLI
    • Requires terminal interaction for wallet operations
    • Best for development and testing
  • Daemon Mode (MNEMONIC set):
    • Set MNEMONIC="your twelve word seed phrase here"
    • Runs automatically in background without interaction
    • Automatically loads wallet on startup
    • Best for production deployments

3. Create Docker Compose File

Create a docker-compose.yml file in your docker/ directory:

services:
  hydra-app:
    image: ghcr.io/offchain-dex/hydra-app:testnet
    volumes:
      - ./config.yaml:/app/config.yaml
    env_file:
      - .env
    environment:
      - GRPC_PORT=${GRPC_PORT}
      - DATA_PATH_NAME=${DATA_PATH_NAME}
    tty: true
    ports:
      - "5001:5001"
    stdin_open: true
    restart: unless-stopped

4. Start the Backend

Run the Hydranet App:

docker-compose up -d

# View logs
docker-compose logs -f hydra-app

# Check status
docker-compose ps

5. Alternative: Run with Standalone Docker

docker run -d \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --env-file .env \
  -e GRPC_PORT=5001 \
  -e DATA_PATH_NAME=hydra-app \
  -p 5001:5001 \
  --name hydra-app \
  ghcr.io/offchain-dex/hydra-app:testnet

Check logs for successful startup:

docker-compose logs hydra-app | grep "gRPC server listening"

That's it! Your Hydranet App backend is now running and ready to accept gRPC-Web connections from your client applications.

For client implementation examples and API usage, see the other documentation sections.

Frontmatter Reference for Nuxt Studio

Important: Remove the # Title H1 heading from each file after adding frontmatter. Nuxt Content automatically renders the title from frontmatter as H1, so having both creates duplicates.

Introduction

Overview and key concepts

Copyright © 2025