ShredStream/ Docs
All Docs

API Reference

The ShredStream.com Provisioning API allows you to programmatically manage your shred streams. All endpoints require authentication via an API key passed in the Authorization header.

Base URL

https://api.shredstream.com/v1

Authentication

Include your API key in every request. You can generate an API key from the ShredStream.com dashboard under Settings > API Keys.

bash
curl -H "Authorization: Bearer ss_live_abc123..." \
  https://api.shredstream.com/v1/status

POST /activate

Activate a shred stream for a given IP and port. The stream begins delivering UDP packets within seconds after the call succeeds. If the subscription has not been paid or has expired, the endpoint returns a 402 error.

Request Body

FieldTypeRequiredDescription
ipstringYesPublic IPv4 address to send shreds to
portintegerYesUDP port number (1024-65535)
regionstringNoPreferred region: us-east, eu-west, ap-tokyo. Defaults to nearest.

Example

curl -X POST https://api.shredstream.com/v1/activate \
  -H "Authorization: Bearer ss_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "203.0.113.42",
    "port": 8001,
    "region": "us-east"
  }'

Response (200 OK)

json
{
  "stream_id": "str_7xKp2mNqR4",
  "status": "active",
  "ip": "203.0.113.42",
  "port": 8001,
  "region": "us-east",
  "activated_at": "2025-06-15T10:30:00Z",
  "expires_at": "2025-07-15T10:30:00Z"
}

Error Responses

StatusMeaning
400Invalid IP address, port out of range, or malformed JSON
401Missing or invalid API key
402No active subscription or subscription expired
409A stream is already active for this IP:port pair

POST /deactivate

Stop a running shred stream immediately. The stream ceases UDP delivery within a few seconds. This does not refund remaining subscription time.

Request Body

FieldTypeRequiredDescription
stream_idstringYesThe stream ID returned from /activate

Example

curl -X POST https://api.shredstream.com/v1/deactivate \
  -H "Authorization: Bearer ss_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "stream_id": "str_7xKp2mNqR4" }'

Response (200 OK)

json
{
  "stream_id": "str_7xKp2mNqR4",
  "status": "deactivated",
  "deactivated_at": "2025-06-15T12:00:00Z"
}

GET /status

Retrieve the status of all your active streams, including throughput metrics and subscription details.

Query Parameters

ParamTypeRequiredDescription
stream_idstringNoFilter to a specific stream. Omit to return all streams.

Example

bash
curl https://api.shredstream.com/v1/status \
  -H "Authorization: Bearer ss_live_abc123..."


# Or filter by stream_id:
curl "https://api.shredstream.com/v1/status?stream_id=str_7xKp2mNqR4" \
  -H "Authorization: Bearer ss_live_abc123..."

Response (200 OK)

json
{
  "streams": [
    {
      "stream_id": "str_7xKp2mNqR4",
      "status": "active",
      "ip": "203.0.113.42",
      "port": 8001,
      "region": "us-east",
      "activated_at": "2025-06-15T10:30:00Z",
      "expires_at": "2025-07-15T10:30:00Z",
      "metrics": {
        "shreds_sent_24h": 48230912,
        "bytes_sent_24h": 55721533440,
        "avg_latency_ms": 1.2,
        "packet_loss_pct": 0.003
      }
    }
  ],
  "subscription": {
    "plan": "ultra",
    "status": "active",
    "current_period_end": "2025-07-15T10:30:00Z"
  }
}

GET /health

Check the health of ShredStream.com infrastructure. This endpoint does not require authentication and is intended for monitoring integrations.

Example

bash
curl https://api.shredstream.com/v1/health

Response (200 OK)

json
{
  "status": "healthy",
  "regions": {
    "us-east": { "status": "operational", "latency_ms": 0.8 },
    "eu-west": { "status": "operational", "latency_ms": 1.1 },
    "ap-tokyo": { "status": "operational", "latency_ms": 1.4 }
  },
  "solana_slot": 284729103,
  "version": "1.4.2",
  "timestamp": "2025-06-15T12:00:00Z"
}

Rate Limits

API requests are rate-limited to 60 requests per minute per API key. The /health endpoint is rate-limited to 300 requests per minute per IP. Rate limit headers are included in every response:

text
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1718448060

SDKs and Libraries

While the REST API works from any language, we publish official SDKs for convenience:

  • Python — pip install shredstream
  • JavaScript/TypeScript — npm install @shredstream/sdk
  • Rust — cargo add shredstream-sdk
ShredStream.com — Fastest Solana Shred Streaming