Skip to main content

API Overview

The Crystara API provides developers with programmatic access to data from the Crystara marketplace, including lootboxes, tokens, collections, and market activities. This document provides an overview of how to use the API.

Base URLs​

The API is available on both Testnet and Mainnet environments:

  • Testnet: https://api.crystara.trade/testnet
  • Mainnet: https://api.crystara.trade/mainnet

Authentication​

All API requests require an API key, which should be included in the x-api-key header.

// Example request with API key
fetch('https://api.crystara.trade/mainnet/lootbox?creator=0x123&collection=MyCollection', {
  headers: {
    'x-api-key': 'your-api-key-here'
  }
})
.then(response => response.json())
.then(data => console.log(data));

To obtain an API key, please see the Register an API Key documentation.

Rate Limits​

API usage is subject to rate limits based on your tier:

  • Free Tier: 1,000 requests per minute, 1,000,000 monthly requests
  • Premium Tier: 10,000 requests per minute, 100,000,000 monthly requests

If you exceed your rate limit, the API will return a 429 (Too Many Requests) status code.

Response Format​

All responses are returned in JSON format. Successful responses typically include the requested data, while error responses include an error message and appropriate HTTP status code.

Success Response​

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Response​

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Resource not found"
  }
}

Common HTTP Status Codes​

CodeDescription
200OK - The request was successful
400Bad Request - The request was invalid
401Unauthorized - API key is missing or invalid
403Forbidden - The API key doesn't have access to the requested resource
404Not Found - The requested resource doesn't exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on our end

Pagination​

Many endpoints that return lists of items support pagination through page and limit parameters:

  • page: The page number (starting from 1)
  • limit: The number of items per page (typically 1, 10, or 100)
// Example request with pagination
fetch('https://api.crystara.trade/mainnet/api/rankings/trending-collections?page=2&limit=10', {
  headers: {
    'x-api-key': 'your-api-key-here'
  }
})

Network Differences​

  • Testnet: Used for testing and development. Data here is not considered production.
  • Mainnet: Production environment with real data.

When developing applications, we recommend starting with the Testnet environment before moving to Mainnet.

Need Help?​

If you need a specific route that isn't currently available, or have questions about the API, please reach out to [email protected].

Note: These routes were last updated April 2, 2025.