# SocioLogic RNG API - Full Documentation

> Cryptographically secure random number generation API with x402 micropayments on Base (Ethereum L2).

SocioLogic RNG provides verifiable entropy for AI agents, games, simulations, and any application requiring unbiased randomness. All random values are generated using `crypto.getRandomValues()` with rejection sampling to eliminate modulo bias.

## Quick Start

All paid endpoints require x402 payment. Send a request, receive a 402 Payment Required response with payment details, complete the USDC payment on Base, then retry with the payment proof.

## Endpoints

### Free Endpoints (No Payment Required)

#### GET /
Returns API information, pricing, and endpoint documentation.

#### GET /health
Returns service status.
Response: `{"status": "ok", "timestamp": "2025-01-21T12:00:00.000Z"}`

#### GET /.well-known/x402
Returns x402 discovery document with resource list and ownership proof.

#### GET /.well-known/x402.json
Returns machine-readable x402 payment manifest with endpoint pricing.

---

### Standard Tier - $0.01 per call

#### GET /random
Generate a cryptographically secure random float between 0 (inclusive) and 1 (exclusive).

**Response:**
```json
{
  "value": 0.7234891,
  "type": "float",
  "range": [0, 1],
  "entropy": {
    "raw": 3104782163,
    "hex": "b9234b53"
  }
}
```

#### GET /random/int
Generate a cryptographically secure random integer within a specified range.

**Query Parameters:**
- `min` (optional, default: 0): Minimum value (inclusive)
- `max` (optional, default: 100): Maximum value (inclusive)

**Constraints:**
- Range must be 1,000,000 or less
- Values must be safe integers (within ±2^53-1)

**Response:**
```json
{
  "value": 42,
  "type": "integer",
  "range": [0, 100],
  "entropy": {
    "raw": 1782349123,
    "hex": "6a3f2c43"
  }
}
```

#### GET /uuid
Generate a cryptographically secure UUID v4.

**Response:**
```json
{
  "value": "550e8400-e29b-41d4-a716-446655440000",
  "type": "uuid",
  "version": 4,
  "entropy": {
    "raw": [1426982912, 3818316244, 2803458664, 1431699456],
    "hex": ["550e8400", "e29b41d4", "a7164466", "55440000"]
  }
}
```

---

### Extended Tier - $0.02 per call

#### GET /dice
Roll a die with configurable number of sides.

**Query Parameters:**
- `sides` (optional, default: 6): Number of sides (2-1000)

**Response:**
```json
{
  "roll": 4,
  "sides": 6,
  "entropy": {
    "raw": 892341567,
    "hex": "352f4a3f"
  }
}
```

#### GET /coin
Flip a coin.

**Response:**
```json
{
  "flip": "heads",
  "entropy": {
    "raw": 1234567890,
    "hex": "499602d2"
  }
}
```

#### POST /shuffle
Shuffle an array using the Fisher-Yates algorithm.

**Request Body:** JSON array of items (max 1000 items, 100KB payload limit)
```json
["a", "b", "c", "d", "e"]
```

**Response:**
```json
{
  "shuffled": ["c", "a", "e", "b", "d"],
  "count": 5,
  "entropy": {
    "raw": [892341567, 123456789, 987654321, 456789012],
    "hex": ["352f4a3f", "075bcd15", "3ade68b1", "1b3d4f94"]
  }
}
```

#### POST /weighted
Select a random item from weighted options.

**Request Body:**
```json
{
  "items": ["common", "uncommon", "rare", "legendary"],
  "weights": [0.7, 0.2, 0.08, 0.02]
}
```

**Constraints:**
- Max 1000 items
- Weights must be non-negative finite numbers
- Total weight must be greater than 0

**Response:**
```json
{
  "selected": "common",
  "selectedIndex": 0,
  "probability": 0.7,
  "entropy": {
    "raw": 456789012,
    "hex": "1b3d4f94"
  }
}
```

---

## Error Handling

All errors return JSON with this structure:
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}
```

**Common Error Codes:**
- `INVALID_INPUT`: Invalid parameter values
- `INVALID_RANGE`: min > max for integer range
- `RANGE_TOO_LARGE`: Range exceeds 1,000,000
- `ARRAY_TOO_LARGE`: Array exceeds 1,000 items
- `PAYLOAD_TOO_LARGE`: Request body exceeds 100KB
- `INVALID_JSON`: Malformed JSON body
- `INVALID_WEIGHTS`: Invalid weight values
- `RATE_LIMITED`: Too many requests (free endpoints only)

---

## Payment Details

### x402 Protocol
This API uses the x402 payment protocol for micropayments.

**Network:** Base Mainnet (Chain ID: 8453)
**Currency:** USDC
**Facilitator:** Coinbase Developer Platform
**Payment Address:** 0x0b6E3594Df4Faa6D66196D5a3271796AD8Bb505d

### Payment Flow
1. Request a paid endpoint
2. Receive 402 Payment Required with payment instructions
3. Submit USDC payment on Base
4. Retry request with X-PAYMENT header containing payment proof
5. Receive response

---

## Technical Details

### Random Number Generation
- Algorithm: CSPRNG with rejection sampling
- Implementation: Web Crypto API (`crypto.getRandomValues()`)
- Bias: Eliminated via rejection sampling
- Verification: Raw entropy values included in every response

### Deployment
- Platform: Cloudflare Workers
- Latency: <100ms globally
- Availability: 99.9%+ uptime

---

## Rate Limits

**Free endpoints only (/, /health):**
- 60 requests per minute per IP
- No rate limits on paid endpoints

---

## Contact

- Website: https://www.sociologic.ai
- Email: team@sociologic.ai
- Documentation: https://www.sociologic.ai/docs