synor/apps/api-gateway/README.md

Synor Public API Gateway

Rate-limited, authenticated access to Synor blockchain RPC.

Quick Start

# Start with API profile
docker compose -f docker-compose.testnet.yml --profile api up -d

# Test the API
curl http://localhost:17400/health

# Make an RPC call (anonymous - 100 req/min)
curl -X POST http://localhost:17400/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"synor_getBlockCount","params":[],"id":1}'

Rate Limit Tiers

Tier	Rate Limit	Price	Features
Free	100 req/min	$0	Anonymous or API key
Developer	1000 req/min	$49/mo	API key + analytics
Enterprise	Unlimited	Custom	SLA, dedicated support

Authentication

API Key Header

curl -X POST http://localhost:17400/rpc \
  -H "Authorization: Bearer sk_developer_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"synor_getBlockCount","params":[],"id":1}'

X-API-Key Header

curl -X POST http://localhost:17400/rpc \
  -H "X-API-Key: sk_developer_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"synor_getBlockCount","params":[],"id":1}'

Query Parameter

curl -X POST "http://localhost:17400/rpc?api_key=sk_developer_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"synor_getBlockCount","params":[],"id":1}'

Rate Limit Headers

All RPC responses include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067260
X-RateLimit-Tier: developer

API Endpoints

Public Endpoints

Health Check

GET /health

Returns service health status.

JSON-RPC Proxy

POST /rpc

Proxies JSON-RPC requests to the Synor node.

Admin Endpoints

Requires Authorization: Bearer <ADMIN_KEY> header.

Create API Key

POST /v1/keys
Content-Type: application/json

{
  "tier": "developer",
  "name": "My App"
}

Response:

{
  "key": "sk_developer_abc123...",
  "tier": "developer",
  "name": "My App",
  "createdAt": 1704067200000,
  "lastUsed": 0,
  "requestCount": 0
}

List API Keys

GET /v1/keys

Get Key Stats

GET /v1/keys/:key/stats

(Accessible by key owner or admin)

Revoke API Key

DELETE /v1/keys/:key

Error Responses

Rate Limit Exceeded (429)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32005,
    "message": "Rate limit exceeded",
    "data": {
      "retryAfter": 45,
      "tier": "free",
      "upgrade": "Upgrade to Developer tier for 1000 req/min"
    }
  },
  "id": null
}

Invalid API Key (401)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Invalid API key"
  },
  "id": null
}

RPC Node Unavailable (502)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "RPC node unavailable"
  },
  "id": null
}

Supported RPC Methods

Chain Methods

• synor_getBlockCount - Get current block height
• synor_getBlockHash - Get block hash by height
• synor_getBlock - Get block by hash
• synor_getDAGInfo - Get DAG structure info
• synor_getChainInfo - Get chain statistics

Transaction Methods

• synor_sendRawTransaction - Submit signed transaction
• synor_getTransaction - Get transaction by ID
• synor_getMempool - Get mempool transactions
• synor_estimateFee - Estimate transaction fee

Address Methods

• synor_getBalance - Get address balance
• synor_getUtxos - Get unspent outputs
• synor_getAddressTransactions - Get address history

Contract Methods

• synor_deployContract - Deploy WASM contract
• synor_callContract - Call contract method
• synor_getContractState - Get contract storage

Environment Variables

Variable	Default	Description
PORT	3100	API gateway port
REDIS_URL	redis://localhost:6379	Redis connection URL
RPC_TARGET	http://localhost:16110	Backend RPC node URL
ADMIN_KEY	admin-secret-key	Admin API key

Development

cd apps/api-gateway
npm install
npm run dev

Production Deployment

The API gateway is designed for horizontal scaling:

1. Deploy multiple API gateway instances behind a load balancer
2. All instances share the same Redis for rate limiting
3. Use Redis Cluster for high availability
4. Set unique ADMIN_KEY per environment

Security Considerations

1. Always use HTTPS in production
2. Rotate admin keys regularly
3. Monitor for abuse patterns
4. Set up alerting for high error rates
5. Use Redis AUTH in production