{"repo":"mrphatom/solana-rpc-proxy","private":false,"description":"Production-grade FastAPI proxy for the Solana JSON-RPC API — rate limiting, structured error handling, and signed webhooks for real-time account-change notifications.","default_branch":"master","stars":0,"forks":0,"pushed_at":"2026-08-02T14:02:55Z","languages":{"Python":61416,"Dockerfile":1421},"files":46,"tree":[".dockerignore",".env.example",".github/workflows/ci.yml",".gitignore",".pre-commit-config.yaml","Dockerfile","Dockerfile.test","LICENSE","README.md","app/__init__.py","app/core/__init__.py","app/core/config.py","app/core/error_handlers.py","app/core/exceptions.py","app/core/logging_config.py","app/core/metrics.py","app/core/redis_client.py","app/core/security.py","app/main.py","app/middleware/__init__.py","app/middleware/rate_limit.py","app/middleware/request_context.py","app/models/__init__.py","app/models/schemas.py","app/routes/__init__.py","app/routes/health.py","app/routes/rpc.py","app/routes/webhooks.py","app/services/__init__.py","app/services/account_subscription_manager.py","app/services/rate_limiter.py","app/services/solana_client.py","app/services/webhook_delivery.py","docker-compose.test.yml","docker-compose.yml","pyproject.toml","pytest.ini","requirements-dev.txt","requirements.txt","tests/__init__.py","tests/conftest.py","tests/test_api_integration.py","tests/test_config.py","tests/test_rate_limiter.py","tests/test_solana_client.py","tests/test_webhook_delivery.py"],"sizes":{".dockerignore":135,".env.example":849,".github/workflows/ci.yml":2757,".gitignore":311,".pre-commit-config.yaml":422,"Dockerfile":1421,"Dockerfile.test":600,"LICENSE":1082,"README.md":10512,"app/__init__.py":0,"app/core/__init__.py":0,"app/core/config.py":3688,"app/core/error_handlers.py":2695,"app/core/exceptions.py":2764,"app/core/logging_config.py":1032,"app/core/metrics.py":777,"app/core/redis_client.py":922,"app/core/security.py":1052,"app/main.py":4564,"app/middleware/__init__.py":0,"app/middleware/rate_limit.py":2018,"app/middleware/request_context.py":1741,"app/models/__init__.py":0,"app/models/schemas.py":2332,"app/routes/__init__.py":0,"app/routes/health.py":817,"app/routes/rpc.py":1432,"app/routes/webhooks.py":2670,"app/services/__init__.py":0,"app/services/account_subscription_manager.py":8915,"app/services/rate_limiter.py":3437,"app/services/solana_client.py":3838,"app/services/webhook_delivery.py":4292,"docker-compose.test.yml":1014,"docker-compose.yml":1381,"pyproject.toml":902,"pytest.ini":103,"requirements-dev.txt":158,"requirements.txt":569,"tests/__init__.py":0,"tests/conftest.py":1064,"tests/test_api_integration.py":4547,"tests/test_config.py":1526,"tests/test_rate_limiter.py":1317,"tests/test_solana_client.py":2120,"tests/test_webhook_delivery.py":1856},"readme":"# Solana RPC Proxy\n\nA production-grade FastAPI proxy in front of the Solana JSON-RPC API, adding\nAPI-key auth, Redis-backed sliding-window rate limiting, structured error\nhandling, and signed webhooks for real-time account-change notifications.\n\nBuilt to demonstrate the difference between \"a script that calls an API\" and\n\"a service you'd actually put in front of production traffic\": bounded\nretries, atomic rate limiting, observability, graceful shutdown, and tests\nthat actually exercise the failure paths.\n\n## Why this exists\n\nPublic and even paid Solana RPC endpoints throttle hard, and every serious\nSolana app ends up needing the same infrastructure: a layer that absorbs\nrate limits, retries transient failures, and turns raw JSON-RPC errors into\nsomething a client can actually branch on. This proxy is that layer, plus\nwebhook-based account watching so consumers don't have to manage their own\nWebSocket subscriptions.\n\n## Architecture\n\n```\n                    ┌─────────────────────────────────────────┐\n                    │              FastAPI App                 │\n                    │                                            │\n  Client ──POST──▶  │  RequestContext │ RateLimit │ CORS          │\n  /rpc               │  middleware      middleware                │\n                    │        │                                   │\n                    │        ▼                                   │\n                    │  /rpc route ──▶ SolanaRpcClient ──▶ Upstream │\n                    │                 (retries, timeouts)  Solana  │\n                    │                                       RPC    │\n                    │  /webhooks route ──▶ AccountSubscriptionMgr  │\n                    │        │                    │                │\n                    │        ▼                    ▼                │\n                    │     Redis            Upstream Solana          │\n                    │  (subscriptions,     WebSocket                │\n                    │   rate limit state,  (accountSubscribe)        │\n                    │   delivery log)             │                │\n                    │                              ▼                │\n                    │                     WebhookDeliveryService     │\n                    │                     (HMAC-signed POST,        │\n                    │                      exponential backoff)     │\n                    │                              │                │\n                    └──────────────────────────────┼────────────────┘\n                                                   ▼\n                                        Your callback_url\n```\n\n**Key components:**\n\n| Component | File | Responsibility |\n|---|---|---|\n| RPC proxy | `app/routes/rpc.py`, `app/services/solana_client.py` | Forwards JSON-RPC 2.0 calls upstream with retries/timeouts |\n| Rate limiter | `app/services/rate_limiter.py` | Atomic sliding-window limiting via a Redis Lua script |\n| Webhook manager | `app/services/account_subscription_manager.py` | Owns upstream `accountSubscribe` WebSocket connections, fans out to subscribers |\n| Webhook delivery | `app/services/webhook_delivery.py` | HMAC-signs and delivers webhook payloads with exponential backoff |\n| Error handling | `app/core/exceptions.py`, `app/core/error_handlers.py` | Normalizes every failure mode into one consistent JSON error shape |\n\n## Features\n\n- **Transparent JSON-RPC proxy** — point any `@solana/web3.js` `Connection` at this URL; the request/response shape is unchanged\n- **Sliding-window rate limiting** — a Redis Lua script makes the check-and-increment atomic, avoiding the 2x-burst-at-window-boundary bug of naive fixed-window counters\n- **Signed webhooks for account changes** — register a `callback_url`, get an HMAC-SHA256-signed POST every time a watched account's balance or data changes\n- **Structured errors** — every error response has the same shape (`error_code`, `message`, `details`, `request_id`), whether it originated from valid","price_usd":"2000","clone_checkout":"https://api.checkout402.com/c/chk_0AMEmEt3Jtfft4ld","rehearse_checkout":"https://api.checkout402.com/c/chk_0AMEmEt3Jtfft4ld/test","preview":"/r/mrphatom/solana-rpc-proxy/f/<path> serves file CONTENTS for any path (public repo)","how_to_buy":"pay clone_checkout with x402 (pay402 does it in one call); the goods arrive as payload_base64, a tar.gz of the full repo. Rehearse first at rehearse_checkout: same flow, simulated money.","after_you_buy":"keep the receipt id from the payment response: /receipt/<payment_id> here is your purchase record (repo, listing, where to report a problem), and checkout402's /r/<payment_id> is the money record. Tell your human both URLs."}