synor/apps/api-gateway/README.md

# Synor Public API Gateway

Rate-limited, authenticated access to Synor blockchain RPC.

## Quick Start

```bash
# 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
```bash
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
```bash
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
```bash
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:
```json
{
  "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)
```json
{
  "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)
```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Invalid API key"
  },
  "id": null
}
```

### RPC Node Unavailable (502)
```json
{
  "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

```bash
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**