REST API v2 • Multi-Chain

API Documentation

Integrate ClearUTXO's UTXO analysis and blockchain data into your applications. Supports Bitcoin and Litecoin.

Authentication

API v2 requires authentication via API Key. Include your key in the X-API-Key header:

bash

curl 'https://api.gliese.io/api/api/v2/status?chain=btc' \
  -H 'X-API-Key: YOUR_API_KEY'

Keep your API key secret

Never expose your API key in client-side code. Always make API calls from your backend.

API Key Plans

API access requires Pro or Enterprise plan. Create API keys from your dashboard.

Rate Limits & Quotas

Rate limits are enforced per API key. Monthly quotas reset on the 1st of each month.

Plan	Requests/min	Monthly Quota	UTXO Limit	Batch
Basic	60	10,000	100	10 addresses
Pro	200	250,000	5,000	100 addresses
Enterprise	1,000	Unlimited	Unlimited	1,000 addresses

Response Headers

Every response includes headers to help you track your usage:

Header	Description
X-API-Limit	Monthly request limit (or "unlimited")
X-API-Remaining	Remaining requests this month
X-API-Reset	ISO timestamp when quota resets
X-API-Plan	Your current plan (pro, enterprise)

Endpoints

GET/status

Get blockchain status including block height, difficulty, hashrate, and mempool info.

Query Parameters

Name	Type	Default	Description
chain	string	btc	Chain ID: btc, ltc

Example Request

bash

curl 'https://api.gliese.io/api/api/v2/status?chain=btc' \
  -H 'X-API-Key: YOUR_API_KEY'

Example Response

json

{
  "success": true,
  "data": {
    "chain": "btc",
    "chainName": "Bitcoin",
    "symbol": "BTC",
    "blockHeight": 876543,
    "difficulty": 95672847567234,
    "hashrate": "756.23 EH/s",
    "mempoolSize": 45230,
    "synced": true,
    "source": "rpc"
  }
}

GET/chains

Get list of all supported blockchain networks.

Example Response

json

{
  "success": true,
  "data": {
    "chains": [
      {
        "id": "btc",
        "name": "Bitcoin",
        "symbol": "BTC",
        "enabled": true
      },
      {
        "id": "ltc",
        "name": "Litecoin",
        "symbol": "LTC",
        "enabled": true
      }
    ]
  }
}

GET/fees

Get current fee estimates for different priority levels.

Query Parameters

Name	Type	Description
chain	string	Chain ID (btc, ltc)

Example Response

json

{
  "success": true,
  "data": {
    "low": 5,
    "medium": 12,
    "high": 25,
    "urgent": 50,
    "unit": "sat/vB",
    "source": "rpc",
    "mempoolSize": 45230,
    "timestamp": "2026-01-16T12:00:00.000Z"
  }
}

GET/address/{address}

Get address information including balance, transaction count, and total received/sent.

Query Parameters

Name	Type	Description
chain	string	Chain ID (btc, ltc)
sync	boolean	Wait for stats calculation (Pro+)

Example Request

bash

curl 'https://api.gliese.io/api/api/v2/address/bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh?chain=btc' \
  -H 'X-API-Key: YOUR_API_KEY'

Example Response

json

{
  "success": true,
  "data": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "chain": "btc",
    "balance": 45230000,
    "balanceFormatted": "0.45230000",
    "totalReceived": 125000000,
    "totalSent": 79770000,
    "txCount": 42,
    "unconfirmedBalance": 0,
    "calculating": false
  }
}

GET/address/{address}/utxos

Get list of UTXOs (unspent transaction outputs) for an address.

Query Parameters

Name	Type	Description
chain	string	Chain ID (btc, ltc)
limit	integer	Max UTXOs to return (plan-based limit)

Example Response

json

{
  "success": true,
  "data": {
    "address": "bc1q...",
    "chain": "btc",
    "utxos": [
      {
        "txid": "a1b2c3d4e5f6...",
        "vout": 0,
        "value": 25000000,
        "valueFormatted": "0.25000000",
        "confirmations": 1234
      }
    ],
    "count": 5,
    "limited": false
  }
}

GET/address/{address}/txs

Get paginated transaction history for an address.

Query Parameters

Name	Type	Description
chain	string	Chain ID (btc, ltc)
page	integer	Page number (default: 1)
pageSize	integer	Transactions per page (default: 25, max: 100)

GET/tx/{txid}

Get detailed transaction information including inputs, outputs, and fee data.

Example Request

bash

curl 'https://api.gliese.io/api/api/v2/tx/4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b?chain=btc' \
  -H 'X-API-Key: YOUR_API_KEY'

Example Response

json

{
  "success": true,
  "data": {
    "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
    "hash": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
    "version": 1,
    "size": 204,
    "vsize": 204,
    "weight": 816,
    "locktime": 0,
    "blockHash": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
    "blockHeight": 0,
    "confirmations": 876543,
    "fee": 0,
    "inputs": [
      {
        "isCoinbase": true
      }
    ],
    "outputs": [
      {
        "n": 0,
        "value": 5000000000,
        "valueFormatted": "50.00000000",
        "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      }
    ]
  }
}

GET/block/{hashOrHeight}

Get block details by hash or height.

Query Parameters

Name	Type	Description
chain	string	Chain ID (btc, ltc)
txids	boolean	Include transaction IDs

Example Request

bash

curl 'https://api.gliese.io/api/api/v2/block/0?chain=btc' \
  -H 'X-API-Key: YOUR_API_KEY'

POST/simulate

Simulate a transaction to estimate fees, select optimal UTXOs, and preview the result.

Request Body

Parameter	Type	Required	Description
chain	string	No	Chain ID (default: btc)
fromAddress	string	Yes	Source address
toAddress	string	Yes	Destination address
amount	integer	Yes	Amount in satoshis
feeRate	integer	No	Fee rate in sat/vB (default: 10)
utxoSelection	string	No	Strategy: optimal, largest, smallest, oldest

Example Request

bash

curl -X POST 'https://api.gliese.io/api/api/v2/simulate' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "chain": "btc",
    "fromAddress": "bc1q...",
    "toAddress": "bc1p...",
    "amount": 100000,
    "feeRate": 15
  }'

Example Response

json

{
  "success": true,
  "data": {
    "viable": true,
    "chain": "btc",
    "amount": 100000,
    "feeRate": 15,
    "estimatedFee": 2250,
    "estimatedSize": 150,
    "selectedUtxos": [
      {
        "txid": "abc...",
        "vout": 0,
        "value": 150000
      }
    ],
    "inputCount": 1,
    "outputCount": 2,
    "totalInput": 150000,
    "totalOutput": 147750,
    "change": 47750,
    "effectiveFeeRate": 15,
    "dustThreshold": 546
  }
}

GET/health/{address}

Return a minimal UTXO health score for widget and lightweight integrations.

Query Parameters

Name	Type	Default	Description
chain	string	btc	Chain ID (btc, ltc)

Example Request

bash

curl 'https://api.gliese.io/api/api/v2/health/bc1q...?chain=btc' \
  -H 'X-API-Key: YOUR_API_KEY'

Example Response

json

{
  "success": true,
  "data": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "chain": "btc",
    "score": 85,
    "grade": "A",
    "utxoCount": 5,
    "balance": 1500000,
    "issues": [
      "2 dust UTXOs",
      "1 unconfirmed"
    ]
  }
}

GET/analyze/{address}

Perform comprehensive UTXO analysis on an address including privacy score, dust detection, and consolidation recommendations.

Query Parameters

Name	Type	Description
chain	string	Chain ID (btc, ltc)

Example Request

bash

curl 'https://api.gliese.io/api/api/v2/analyze/bc1q...?chain=btc' \
  -H 'X-API-Key: YOUR_API_KEY'

GET/usage

Get your current API usage statistics for the billing period.

Example Response

json

{
  "success": true,
  "data": {
    "plan": "pro",
    "period": {
      "start": "2026-01-01T00:00:00.000Z",
      "end": "2026-02-01T00:00:00.000Z"
    },
    "usage": {
      "apiCalls": 15420,
      "limit": 100000,
      "remaining": 84580,
      "percentUsed": 15.42
    },
    "limits": {
      "utxoLimit": 1000,
      "batchLimit": 50,
      "syncCalculation": true
    }
  }
}

POST/analyze/batchPro+

Analyze multiple addresses in a single request. Available for Pro and Enterprise plans.

Request Body

Parameter	Type	Description
addresses	string[]	Array of addresses (max 50 Pro, 500 Enterprise)
chain	string	Chain ID (btc, ltc)
webhookUrl	string	URL for async result callback (optional)

Example Request

bash

curl -X POST 'https://api.gliese.io/api/api/v2/analyze/batch' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "addresses": ["bc1q...", "bc1p...", "3ABC..."],
    "chain": "btc"
  }'

Analytics Dashboard

Monitor your API usage with detailed analytics. Access via /api/v1/analytics/* endpoints (requires JWT auth).

Endpoint	Description
/analytics/overview	Overview stats, success rates, request counts
/analytics/endpoints	Usage breakdown by endpoint
/analytics/chains	Usage breakdown by chain (BTC/LTC)
/analytics/charts/hourly	Hourly time series for charts
/analytics/charts/daily	Daily time series for charts
/analytics/errors	Recent error logs
/analytics/logs	Paginated request logs with filters
/analytics/summary	All stats in one request

Error Codes

The API uses standard HTTP status codes and returns JSON error responses.

Code	Meaning
`200`	Success
`400`	Bad Request - Invalid parameters or address format
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Feature not available for your plan
`404`	Not Found - Resource does not exist
`429`	Rate Limit / Quota Exceeded
`500`	Internal Server Error
`503`	Service Unavailable - Node not synced

Error Response Format

json

{
  "success": false,
  "error": "Invalid address format",
  "code": "INVALID_ADDRESS"
}

Quota Exceeded Error

json

{
  "success": false,
  "error": "Monthly API limit exceeded",
  "code": "API_LIMIT_EXCEEDED",
  "limit": 100000,
  "used": 100000,
  "resetDate": "2026-02-01T00:00:00.000Z",
  "upgradeUrl": "/pricing"
}

Client Libraries

Use our Node.js client as a starting point for integration:

javascript

// Install: npm install node-fetch
import fetch from 'node-fetch'

const API_KEY = 'sk_live_your_api_key'
const BASE_URL = 'https://api.gliese.io/api/api/v2'

async function getStatus(chain = 'btc') {
  const response = await fetch(`${BASE_URL}/status?chain=${chain}`, {
    headers: { 'X-API-Key': API_KEY }
  })
  return response.json()
}

async function getAddress(address, chain = 'btc') {
  const response = await fetch(`${BASE_URL}/address/${address}?chain=${chain}`, {
    headers: { 'X-API-Key': API_KEY }
  })
  return response.json()
}

async function simulate(params) {
  const response = await fetch(`${BASE_URL}/simulate`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(params)
  })
  return response.json()
}

// Usage
const status = await getStatus('btc')
console.log(status)

Official SDKs for Python, Go, and Rust coming soon.