Skip to content

api.md

Latest commit

 

History

History
362 lines (293 loc) · 8.85 KB

api.md

File metadata and controls

362 lines (293 loc) · 8.85 KB

SolBug API Documentation

The SolBug API provides programmatic access to our Solana error translation engine. Transform cryptic blockchain errors into clear, actionable solutions.

Quick Start

Base URL

Production: https://api.solbug.dev
Self-hosted: http://localhost:8787

Authentication

All API requests require an API key in the header:

X-API-Key: your_api_key_here

Get your free API key at solbug.dev

Rate Limits

Tier Requests/Month Rate Limit Price
Free 1,000 10/min $0
Pro 50,000 100/min $49/month
Enterprise Unlimited 1000/min $499/month

Rate limit headers are included in all responses:

X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200

Endpoints

POST /translate

Translate a Solana transaction error into human-readable format.

Request

POST /translate
Content-Type: application/json
X-API-Key: your_api_key

{
  "signature": "5KJo7nKj8vQ2pL9X3mR4nB6tY2qWzGxQvH8M9uE3sT6rL1vN4jR8pQ5xK2yF7bA3zC9wD6mS8eH",
  "rpc": "https://api.mainnet-beta.solana.com" // optional
}

Response

{
  "input": {
    "signature": "5KJo7nKj8vQ2pL9X3mR4nB6tY2qWzGxQvH8M9uE3sT6rL1vN4jR8pQ5xK2yF7bA3zC9wD6mS8eH"
  },
  "raw": "Program log: Instruction: Transfer\nProgram log: Error: InsufficientFunds",
  "result": {
    "title": "Insufficient SOL for transaction fees or rent",
    "explanation": "The fee payer account lacks enough lamports to cover transaction fees, or an account doesn't meet rent-exempt minimums. This is the most common Solana error.",
    "confidence": 0.98,
    "source": "pattern",
    "category": "transaction",
    "severity": "medium",
    "quickFix": "Add more SOL to your wallet",
    "links": [
      {
        "label": "Rent-exempt minimum calculator",
        "url": "https://docs.solana.com/developing/programming-model/accounts#rent-exemption"
      }
    ]
  }
}

Parameters

Parameter Type Required Description
signature string Yes Solana transaction signature (base58)
rpc string No Custom RPC endpoint URL

Response Fields

Field Type Description
input object Echo of request parameters
raw string Raw transaction logs and error data
result object|null Translation result (null if no pattern matched)
result.title string Brief, clear error title
result.explanation string Detailed explanation with solution
result.confidence number Confidence score (0.0-1.0)
result.source string "pattern" or "ai"
result.category string Error category (transaction, account, program, etc.)
result.severity string Severity level (low, medium, high, critical)
result.quickFix string One-sentence immediate action
result.links array Helpful documentation links

GET /health

Check API health and system status.

Request

GET /health

Response

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 86400,
  "version": "1.2.0",
  "providers": [
    {
      "name": "helius",
      "url": "https://***",
      "weight": 4,
      "consecutiveFailures": 0,
      "lastFailure": null
    }
  ],
  "aiEnabled": true,
  "analytics": {
    "totalRequests": 15420,
    "cacheHitRate": 0.65,
    "patternMatchRate": 0.78,
    "aiFallbackRate": 0.15,
    "avgResponseTime": 342,
    "healthScore": 95
  }
}

POST /feedback

Provide feedback on translation quality.

Request

POST /feedback
Content-Type: application/json
X-API-Key: your_api_key

{
  "signature": "5KJo7nKj8vQ2pL9X3mR4nB6tY2qWzGxQvH8M9uE3sT6rL1vN4jR8pQ5xK2yF7bA3zC9wD6mS8eH",
  "helpful": true,
  "comment": "Great explanation, helped me fix the issue quickly!"
}

Response

{
  "status": "ok",
  "message": "Feedback recorded"
}

Code Examples

JavaScript/TypeScript

const response = await fetch('https://api.solbug.dev/translate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key'
  },
  body: JSON.stringify({
    signature: 'your_transaction_signature'
  })
});

const data = await response.json();

if (data.result) {
  console.log(`Error: ${data.result.title}`);
  console.log(`Solution: ${data.result.explanation}`);
} else {
  console.log('No translation available for this error');
}

Python

import requests

response = requests.post(
    'https://api.solbug.dev/translate',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key'
    },
    json={
        'signature': 'your_transaction_signature'
    }
)

data = response.json()

if data.get('result'):
    print(f"Error: {data['result']['title']}")
    print(f"Solution: {data['result']['explanation']}")
else:
    print("No translation available for this error")

cURL

curl -X POST https://api.solbug.dev/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "signature": "your_transaction_signature"
  }'

Rust

use reqwest;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let response = client
        .post("https://api.solbug.dev/translate")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "your_api_key")
        .json(&json!({
            "signature": "your_transaction_signature"
        }))
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    
    if let Some(result) = data.get("result") {
        println!("Error: {}", result["title"]);
        println!("Solution: {}", result["explanation"]);
    } else {
        println!("No translation available for this error");
    }

    Ok(())
}

Error Handling

HTTP Status Codes

Status Meaning Description
200 Success Translation completed
400 Bad Request Invalid request format
401 Unauthorized Invalid or missing API key
404 Not Found Transaction not found
429 Rate Limited Too many requests
500 Server Error Internal server error

Error Response Format

{
  "error": "Invalid API key",
  "message": "Include your API key in X-API-Key header or Authorization: Bearer <key>",
  "signature": "5KJo7nKj8vQ2pL9X3mR4nB6tY2qWzGxQvH8M9uE3sT6rL1vN4jR8pQ5xK2yF7bA3zC9wD6mS8eH"
}

Best Practices

  • Retry logic: Implement exponential backoff for 429/500 errors
  • Timeout handling: Set reasonable request timeouts (10-30 seconds)
  • Rate limit respect: Monitor rate limit headers
  • Error logging: Log errors for debugging
  • Fallback handling: Handle cases where no translation is available

Self-Hosting

Want to run your own SolBug API instance? Check out our self-hosting guide.

Quick Docker Setup

# Clone repository
git clone https://github.com/yourusername/solbug.git
cd solbug

# Set environment variables
cp .env.example .env
# Edit .env with your configuration

# Start with Docker Compose
docker-compose up -d

# API available at http://localhost:8787

Monitoring

Health Checks

Monitor your API with the /health endpoint:

  • Response time: Should be <500ms
  • Health score: Should be >90
  • Cache hit rate: Should be >60%
  • Pattern match rate: Should be >75%

Metrics to Track

  • Request volume and patterns
  • Error rates by category
  • Response times
  • Cache performance
  • RPC provider health

Security

API Key Security

  • Never expose API keys in client-side code
  • Use environment variables for key storage
  • Rotate keys regularly (quarterly recommended)
  • Monitor usage for suspicious activity

Data Privacy

  • No sensitive data logging: We don't store transaction contents
  • Minimal retention: API logs purged after 30 days
  • GDPR compliant: Request data deletion anytime

Support

Getting Help

SLA (Enterprise)

  • 99.9% uptime guarantee
  • <500ms average response time
  • 24/7 support with <4 hour response
  • Dedicated Slack channel

Additional Resources

Built for the Solana developer community