API Reference

Base URL

Production: https://api.shards.tv/v1 Development: https://dev-api.shards.tv/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Rate Limits

Tier	Requests/Second	Requests/Day	WebSocket Connections
Free	10	10,000	1
Basic	100	100,000	5
Pro	1,000	1,000,000	20
Enterprise	Custom	Unlimited	Unlimited

REST API Endpoints

Oracle Data

Get Current Price

Retrieve the latest price for a specific asset from aggregated oracle sources.

GET /oracle/price/{symbol}

Parameters:

• symbol (path, required): Asset symbol (e.g., "SOL", "BTC", "ETH")

• source (query, optional): Specific oracle source ("pyth", "chainlink", "switchboard", "aggregated")

• confidence (query, optional): Include confidence intervals (boolean)

Response:

{
  "symbol": "SOL",
  "price": 125.45,
  "confidence": 0.12,
  "timestamp": 1674834521,
  "slot": 182453621,
  "sources": [
    {
      "provider": "pyth",
      "price": 125.43,
      "confidence": 0.10,
      "publishers": 15
    },
    {
      "provider": "chainlink",
      "price": 125.47,
      "confidence": 0.15,
      "publishers": 8
    }
  ],
  "aggregation": {
    "method": "weighted_average",
    "weight_factors": ["recency", "publisher_count", "historical_accuracy"]
  }
}

Get Historical Prices

Retrieve historical price data for a specific time range.

GET /oracle/history/{symbol}

Parameters:

• symbol (path, required): Asset symbol

• from (query, required): Start timestamp (Unix epoch)

• to (query, required): End timestamp (Unix epoch)

• resolution (query, optional): Data resolution ("1m", "5m", "15m", "1h", "1d")

• source (query, optional): Specific oracle source

Response:

{
  "symbol": "SOL",
  "resolution": "1h",
  "data": [
    {
      "timestamp": 1674828000,
      "open": 124.50,
      "high": 126.30,
      "low": 124.20,
      "close": 125.45,
      "volume": 1523450.32,
      "confidence": 0.11
    }
  ],
  "metadata": {
    "total_points": 168,
    "sources_used": ["pyth", "chainlink"],
    "missing_data_points": 2
  }
}

Batch Price Request

Retrieve prices for multiple assets in a single request.

POST /oracle/batch

Request Body:

{
  "symbols": ["SOL", "BTC", "ETH", "USDC"],
  "include_metadata": true,
  "source": "aggregated"
}

Response:

{
  "prices": {
    "SOL": {
      "price": 125.45,
      "confidence": 0.12,
      "timestamp": 1674834521
    },
    "BTC": {
      "price": 42153.23,
      "confidence": 15.34,
      "timestamp": 1674834521
    }
  },
  "request_id": "req_abc123",
  "processing_time_ms": 23
}

RPC Data Access

Get Account Info

Retrieve detailed information about a Solana account.

GET /rpc/account/{address}

Parameters:

• address (path, required): Solana account address

• encoding (query, optional): Data encoding ("base58", "base64", "jsonParsed")

• commitment (query, optional): Commitment level ("processed", "confirmed", "finalized")

Response:

{
  "address": "11111111111111111111111111111111",
  "lamports": 1000000000,
  "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "executable": false,
  "rent_epoch": 361,
  "data": {
    "parsed": {
      "type": "token",
      "info": {
        "mint": "So11111111111111111111111111111111111111112",
        "owner": "user_wallet_address",
        "amount": "1000000"
      }
    }
  }
}

Get Program Accounts

Retrieve all accounts owned by a specific program.

GET /rpc/program/{programId}/accounts

Parameters:

• programId (path, required): Solana program ID

• filters (query, optional): JSON-encoded filters

• limit (query, optional): Maximum number of accounts (default: 100, max: 1000)

• offset (query, optional): Pagination offset

LLM Interface

Natural Language Query

Process natural language queries to retrieve oracle data.

POST /llm/query

Request Body:

{
  "query": "What's the current price of Solana and how has it changed in the last 24 hours?",
  "context": {
    "session_id": "session_123",
    "include_confidence": true,
    "preferred_sources": ["pyth", "chainlink"]
  }
}

Response:

{
  "interpretation": {
    "intent": "price_with_change",
    "entities": {
      "asset": "SOL",
      "timeframe": "24h"
    }
  },
  "data": {
    "current_price": 125.45,
    "price_24h_ago": 118.32,
    "change_24h": 7.13,
    "change_24h_percent": 6.02,
    "high_24h": 127.89,
    "low_24h": 117.45
  },
  "natural_response": "Solana is currently trading at $125.45, up 6.02% ($7.13) from $118.32 24 hours ago. The 24-hour range has been $117.45 - $127.89.",
  "sources_used": ["pyth", "chainlink"],
  "confidence_score": 0.95
}

WebSocket API

Connection

const ws = new WebSocket('wss://api.shards.tv/v1/stream');

ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'auth',
    api_key: 'YOUR_API_KEY'
  }));
});

Subscription Messages

Subscribe to Price Updates

{
  "type": "subscribe",
  "channel": "oracle.price",
  "params": {
    "symbols": ["SOL", "BTC"],
    "sources": ["pyth", "chainlink"],
    "min_confidence": 0.95
  }
}

Subscribe to Account Changes

{
  "type": "subscribe",
  "channel": "rpc.account",
  "params": {
    "addresses": ["address1", "address2"],
    "commitment": "confirmed"
  }
}

Message Format

Price Update Message

{
  "type": "price_update",
  "channel": "oracle.price",
  "data": {
    "symbol": "SOL",
    "price": 125.67,
    "previous_price": 125.45,
    "confidence": 0.11,
    "timestamp": 1674834625,
    "slot": 182453745,
    "source": "pyth"
  }
}

GraphQL API

Endpoint

POST /graphql

Schema Examples

Query Current Prices

query GetPrices {
  oraclePrices(symbols: ["SOL", "BTC", "ETH"]) {
    symbol
    price
    confidence
    timestamp
    sources {
      provider
      price
      publishers
    }
  }
}

Query Historical Data

query GetHistory {
  priceHistory(
    symbol: "SOL"
    from: "2024-01-01T00:00:00Z"
    to: "2024-01-07T00:00:00Z"
    resolution: "1h"
  ) {
    timestamp
    open
    high
    low
    close
    volume
  }
}

Subscription for Real-time Updates

subscription PriceUpdates {
  priceUpdate(symbols: ["SOL", "BTC"]) {
    symbol
    price
    confidence
    timestamp
    change24h
  }
}

Error Handling

Error Response Format

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset_at": 1674834681
    }
  },
  "request_id": "req_xyz789",
  "timestamp": 1674834621
}

Common Error Codes

Code	HTTP Status	Description
INVALID_API_KEY	401	Invalid or missing API key
RATE_LIMIT_EXCEEDED	429	Too many requests
INVALID_SYMBOL	400	Requested symbol not supported
DATA_NOT_AVAILABLE	404	No data available for request
INVALID_PARAMETERS	400	Invalid request parameters
INTERNAL_ERROR	500	Internal server error
SERVICE_UNAVAILABLE	503	Service temporarily unavailable

SDK Examples

JavaScript/TypeScript

import { ShardsClient } from '@shards/sdk';

const client = new ShardsClient({
  apiKey: 'YOUR_API_KEY',
  network: 'mainnet'
});

// Get current price
const price = await client.oracle.getPrice('SOL');

// Subscribe to updates
client.stream.subscribe('SOL', (update) => {
  console.log(`New price: ${update.price}`);
});

// Natural language query
const response = await client.llm.query(
  "Show me the 7-day price trend for Solana"
);

Python

from shards import ShardsClient

client = ShardsClient(
    api_key="YOUR_API_KEY",
    network="mainnet"
)

# Get current price
price = client.oracle.get_price("SOL")

# Get historical data
history = client.oracle.get_history(
    symbol="SOL",
    from_time=datetime(2024, 1, 1),
    to_time=datetime(2024, 1, 7),
    resolution="1h"
)

# Natural language query
response = client.llm.query(
    "What's the volatility of Bitcoin over the past month?"
)

Webhooks

Configuration

Register webhook endpoints to receive push notifications for specific events.

POST /webhooks

Request Body:

{
  "url": "https://your-app.com/webhook",
  "events": ["price_change", "confidence_threshold"],
  "config": {
    "price_change": {
      "symbols": ["SOL", "BTC"],
      "threshold_percent": 5
    },
    "confidence_threshold": {
      "min_confidence": 0.90
    }
  }
}

Webhook Payload

{
  "event": "price_change",
  "timestamp": 1674834621,
  "data": {
    "symbol": "SOL",
    "old_price": 120.34,
    "new_price": 126.78,
    "change_percent": 5.35
  },
  "webhook_id": "wh_abc123",
  "signature": "sha256_signature_for_validation"
}