bridge

README

TON Connect Bridge

HTTP bridge implementation for TON Connect 2.0.

🚀 Quick Start

git clone https://github.com/ton-connect/bridge
cd bridge
make build3
./bridge3

For production deployments, use Redis/Valkey storage. See Configuration for details.

Use make help to see all available commands.

Note: For common issues and troubleshooting, see KNOWN_ISSUES.md

📋 Requirements

• Go 1.26+
• Redis/Valkey 7.0+ (or any Redis-compatible storage) for production
• Node.js & npm (for testing)

📚 Documentation

• Architecture - Bridge architecture, pub/sub design, and scaling
• Configuration - Complete environment variables reference
• Deployment - Production deployment patterns and best practices
• Known Issues - Common issues and troubleshooting
• Monitoring - Metrics, health checks, and observability

Looking for PostgreSQL-based setup?

For existing PostgreSQL-based installations, see Bridge v1.

We recommend migrating to the current version — it scales with your user base and receives active development.

The current setup uses Redis/Valkey for pub/sub, enabling horizontal scaling across multiple instances. The PostgreSQL-based version is limited to a single instance and cannot scale horizontally.

Use local TON Connect Bridge

Default url: http://localhost:8081/bridge

Docker

git clone https://github.com/ton-connect/bridge.git
cd bridge
docker compose -f docker/docker-compose.valkey.yml up --build -d
curl -I -f -s -o /dev/null -w "%{http_code}\n" http://localhost:9103/metrics

GitHub Action

Example usage from another repository:

name: e2e
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start Bridge
        uses: ton-connect/bridge/actions/local@master
        with:
          repository: "ton-connect/bridge"
          branch: "master"

      - name: Run E2E tests
        env:
          BRIDGE_URL: http://localhost:8081/bridge
        run: |
          npm run e2e

Made with ❤️ for the TON ecosystem