REST API Overview

The Subfrost REST API provides high-level endpoints for alkanes, AMM pools, and blockchain data. These endpoints are part of the alkanes-data-api service.

Base URLs

Choose the network for your application:

Mainnet:https://mainnet.subfrost.io/v4/api
Signet:https://signet.subfrost.io/v4/api
Regtest:https://regtest.subfrost.io/v4/api

Authentication

  • Public endpoint - /v4/api/{route} (with CORS from registered domain)
  • API key in path - /v4/{api_key}/{route}
  • API key header - /v4/api/{route} with x-subfrost-api-key header

Request Format

All endpoints accept POST requests with JSON bodies.

curl -X POST https://mainnet.subfrost.io/v4/api/get-bitcoin-price \
  -H "Content-Type: application/json" \
  -d '{}'

# Or with API key:
curl -X POST https://mainnet.subfrost.io/v4/YOUR_API_KEY/get-bitcoin-price \
  -H "Content-Type: application/json" \
  -d '{}'

Response Format

All responses follow this structure:

// Success
{
  "statusCode": 200,
  "data": { /* response data */ }
}

// Error
{
  "statusCode": 400,
  "error": "Invalid request parameters"
}

Endpoint Categories

Alkanes

Query alkane tokens and contracts.

EndpointDescription
POST /get-alkanesList all alkanes
POST /get-alkanes-by-addressAlkanes for an address
POST /get-alkane-detailsSpecific alkane info
POST /global-alkanes-searchSearch alkanes

Pools & AMM

Liquidity pools and AMM operations.

EndpointDescription
POST /get-poolsList all pools
POST /get-pool-detailsPool details
POST /get-all-pools-detailsAll pool details
POST /address-positionsLiquidity positions

Bitcoin/UTXOs

Bitcoin balance and UTXO queries.

EndpointDescription
POST /get-address-balanceAddress balance
POST /get-taproot-balanceTaproot balance
POST /get-address-utxosAddress UTXOs
POST /get-account-utxosAccount UTXOs

History

Transaction history for AMM operations.

EndpointDescription
POST /get-pool-swap-historyPool swap history
POST /get-token-swap-historyToken swap history
POST /get-pool-mint-historyLiquidity adds
POST /get-pool-burn-historyLiquidity removes

Bitcoin Price

Real-time BTC price from Uniswap V3 WBTC/USDC pool.

EndpointDescription
POST /get-bitcoin-priceCurrent BTC price in USD
POST /get-bitcoin-market-chartHistorical price data
POST /get-bitcoin-market-weekly52-week high/low

Health Check

GET https://mainnet.subfrost.io/v4/api/health

// Response:
{
  "status": "ok",
  "timestamp": 1699123456
}

JavaScript Example

const API_BASE = 'https://mainnet.subfrost.io/v4/api';

async function getAlkanesByAddress(address) {
  const response = await fetch(`${API_BASE}/get-alkanes-by-address`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ address })
  });

  const data = await response.json();

  if (data.statusCode !== 200) {
    throw new Error(data.error);
  }

  return data.data;
}

const alkanes = await getAlkanesByAddress('bc1p...');
console.log('Alkane holdings:', alkanes);