AWS Hyperliquid Proxy

🚀 Open Source Infrastructure Solution

This is an open source project that provides a fast, reliable, and cost-effective proxy solution for Hyperliquid API calls using AWS infrastructure. We believe in community-driven development and welcome contributions from developers worldwide.

The Problem We're Solving

We understand the pain of building products in the Hyperliquid ecosystem:

• Rate limiting restricts HTTP calls to the Hyperliquid API, limiting innovation
• Public proxies (Brightdata, Oxylabs) can be slow and frustrating for users
• High costs of running dedicated infrastructure

Our Open Source Solution

This repository provisions AWS edge infrastructure for a lightweight Go reverse proxy that:

• Forwards selected requests to https://api.hyperliquid.xyz
• Provides simple health monitoring
• Uses Terraform for complete infrastructure as code
• Combines on-demand and spot instances for cost optimization

💡 Why Open Source?

• Transparency: Full visibility into the proxy implementation
• Community-driven: Benefit from collective improvements and bug fixes
• Cost-effective: No vendor lock-in, deploy on your own AWS account
• Customizable: Adapt the solution to your specific needs
• Educational: Learn modern infrastructure patterns and practices

Check https://instances.vantage.sh for the cheapest spot instances to optimize your costs further.

Tech Stack

• Infrastructure: Terraform for AWS resource provisioning
• Compute: AWS EC2 (on-demand + spot instances)
• Load Balancing: Application Load Balancer (ALB)
• CDN: CloudFront distribution
• Container Registry: Amazon ECR
• Runtime: Go 1.24+
• Containerization: Docker (multi-stage builds)
• Networking: VPC with public subnets, Internet Gateway
• Security: IAM roles, Security Groups
• Scaling: Auto Scaling Groups

Overview

• VPC with two public subnets, Internet Gateway, and routing.
• Security groups for ALB (80/443) and EC2 (8080 from ALB, 22 for SSH).
• Application Load Balancer in front of two Auto Scaling Groups (on‑demand and spot) using launch templates.
• CloudFront distribution in front of the ALB (HTTP origin; redirect to HTTPS at the edge).
• ECR repository for the container image (with lifecycle policy).
• EC2 user data installs Docker and runs the latest image from ECR.
• Go service listens on :8080, proxies /info and /exchange, and serves /health.

Repo Structure

• main.tf: Terraform infrastructure (AWS provider, networking, ALB, ASGs, CloudFront, outputs).
• ecr.tf: ECR repository and lifecycle policy configuration.
• user_data.sh: EC2 bootstrap to install Docker, login to ECR, and run the container.
• main.go: Minimal reverse proxy with retry on 429 and /health endpoint.
• Dockerfile: Multi‑stage build for a small static Go binary image.
• build.sh: Helper to build, tag, and push the image to your account's ECR.
• go.mod: Go module settings.

Prerequisites

• AWS account with permissions for VPC, EC2, ELBv2, CloudFront, IAM, ECR, and Auto Scaling.
• terraform >= 1.0, awscli, docker.
• AWS credentials configured (e.g., aws configure or environment variables).

Quick Start

Prerequisites

1. Verify AWS CLI is properly configured

• Run: aws sts get-caller-identity
• Ensure your AWS credentials are configured (e.g., aws configure or environment variables)
• Verify your default region is set: aws configure get region

2. Create the ECR repository first

• Run: terraform init (if not done already)
• Apply ECR configuration: terraform apply ecr.tf
• Note the ECR repository URL from the output

Build and Deploy

3. Build and push the container image to your ECR

• Ensure Docker is installed and running
• Ensure your AWS CLI default region is set (used by build.sh)
• Run: ./build.sh
• Note the resulting image URI printed at the end

4. Review and adjust configuration

• Region: Terraform defaults to ap-northeast-1 but can be customized using the aws_region variable.
• Instance type: Defaults to t3a.nano but can be customized using the instance_type variable.
• ECR in user data: user_data.sh currently references a hard‑coded ECR URL 415177010443.dkr.ecr.eu-central-1.amazonaws.com/hyperliquid-proxy for pulling the image. Update this to your account and region, or align your push to that repo.
• ASG sizes and CloudFront price class can be tuned in main.tf.

5. Provision the infrastructure

• terraform init
• terraform apply (use -var="aws_region=us-west-2" and -var="instance_type=t3.micro" to override defaults)
• Outputs include the ALB DNS name and the CloudFront domain.

6. Verify

• Health: curl https://<cloudfront_domain>/health (302 → HTTPS; then 200 JSON).
• Proxy: curl https://<cloudfront_domain>/info and /exchange should forward to the Hyperliquid API.

Service Endpoints

• /health: JSON health check from the Go service.
• /info, /exchange: Proxied to api.hyperliquid.xyz with basic 429 retry backoff.

Terraform Outputs

• alb_dns_name: Public DNS of the ALB.
• alb_zone_id: Hosted zone ID for the ALB (useful for Route53 records).
• cloudfront_domain_name: Public domain for the CloudFront distribution.
• ecr_repository_url: ECR repo URI for pushing images.

Customization Notes

• Region: Use the aws_region variable to change the deployment region (default: ap-northeast-1).
• Instance type: Use the instance_type variable to change the EC2 instance type (default: t3a.nano).
• Image source: Replace the hard‑coded image reference in user_data.sh with your ECR URL (or template it via Terraform if desired).
• TLS: CloudFront uses the default certificate for *.cloudfront.net. For custom domains, create an ACM cert in us‑east‑1 and attach it to CloudFront.
• Capacity: Adjust ASG min_size, desired_capacity, and max_size in main.tf.

Cleanup

• terraform destroy tears down all provisioned AWS resources.
• Manually delete any remaining ECR images if the repo is retained by policy.

Troubleshooting

• Image pull failures: Ensure user_data.sh references your correct ECR URL and that the instance role has ECR permissions (configured in main.tf).
• 5xx from ALB/CF: Check EC2 instance logs (docker logs hyperliquid-proxy) and security groups for port 8080.
• Region mismatch: Keep build.sh, main.tf, and user_data.sh aligned on AWS region and account ID.

🤝 Contributing

We welcome contributions from the community! This open source project thrives on collaboration and diverse perspectives.

Ways to Contribute

• 🐛 Bug Reports: Found an issue? Open an issue with detailed reproduction steps
• 💡 Feature Requests: Have ideas for improvements? Share them in the issues
• 🔧 Code Contributions: Submit pull requests for bug fixes or new features
• 📚 Documentation: Help improve guides, examples, and API documentation
• 🧪 Testing: Test the proxy in different AWS regions and configurations
• 💬 Community Support: Help other users in discussions and issues

Getting Started with Development

1. Fork the repository and clone your fork
2. Set up your development environment following the Prerequisites section
3. Make your changes on a feature branch
4. Test thoroughly in your AWS environment
5. Submit a pull request with clear description of changes

Development Guidelines

• Follow existing code style and patterns
• Test infrastructure changes in isolated AWS accounts
• Update documentation for any new features or configuration options
• Keep commits focused and write clear commit messages
• Ensure Terraform plans are clean and follow AWS best practices

Code of Conduct

This project follows standard open source community guidelines:

• Be respectful and inclusive
• Provide constructive feedback
• Focus on technical merits of contributions
• Help create a welcoming environment for all contributors

🗺️ Roadmap & Community Priorities

Help us prioritize! Vote on features or add new ideas by opening issues.

Current Roadmap

• ALB-based Autoscaling: Implement CloudWatch metrics-based autoscaling using ALB request count, target response time, and active connection count to automatically scale ASGs up/down based on traffic patterns.
• Customizable Caching Layer: Add configurable caching to cache API results and reduce load on Hyperliquid API endpoints.
• WebSocket Support: Implement WebSocket proxying for real-time data streaming from Hyperliquid.
• EVM Support: Extend proxy functionality to support RPC endpoints.
• RPS Tracking and Throttling: Implement requests per second tracking and throttling to manage traffic flow.
• Multi-Region Deployment: Template for deploying across multiple AWS regions
• Monitoring & Observability: CloudWatch dashboards and alerting setup
• Cost Optimization Tools: Scripts and recommendations for further cost reduction

Community Requests

Want to see something not listed? Your input shapes the roadmap! Open an issue to suggest new features or improvements.

📄 License

This project is open source and available under the MIT License.

🌟 Support the Project

If this project helps you, consider:

• ⭐ Starring the repository to show your support
• 🔀 Sharing with others who might benefit
• 🤝 Contributing improvements back to the community
• 🐛 Reporting bugs to help improve stability
• 💡 Suggesting features to help the project evolve