API Documentation

Citrusrate V1 API Documentation

Welcome to the Citrusrate V1 API. This API provides real-time and black-market exchange rates for Bitcoin (BTC) and Fiat currencies across Africa.

Supported Currencies (African Fiat)

Citrusrate currently supports 41 African currencies. Use these tickers in the currency query parameter for any endpoint.

Supported Black Market Currencies

We provide parallel market and peer-to-peer (P2P) rate data for these 13 currencies:

L402 Lightning Auth

If you do not have an API key, you can use the L402 protocol. If you send a request without a key, the server returns an HTTP 402 error. This error contains a Lightning invoice.

This is an example of the HTTP 402 (Payment Required) response:

{
  "status": "payment_required",
  "message": "Payment of 500 sats required to access this endpoint.",
  "payment": {
    "macaroon": "ASI2yzTmASi5b5...",
    "invoice": "lnbc500n1p4xp5y9p...",
    "paymentHash": "2236cb34e6...",
    "amount": 500,
    "currency": "SAT",
    "expiresAt": "2026-07-22T14:27:05.000Z"
  },
  "service": {
    "name": "Citrusrate",
    "description": "Real-time FX rates for African currencies",
    "endpoint": "/v1/fiat/mid?currency=MWK"
  }
}

WebSocket Streaming

Citrusrate sends real-time data with Socket.IO for premium plans. Use a standard Socket.IO client to connect. Put your API key in the auth object.

import { io } from "socket.io-client";

const socket = io("wss://api.citrusrate.com/ws/developer/prices", {
  auth: { apiKey: "your_api_key_here" }
});

socket.on("connect", () => console.log("Connected!"));
socket.on("data", (prices) => {
  console.log("Live Prices:", prices);
});

import { io } from "socket.io-client";

const socket = io("wss://api.citrusrate.com/ws/developer/blackmarket", {
  auth: {
    apiKey: "your_api_key_here",
    currencies: ["NGN", "GHS", "KES"] // Max Tier only
  }
});

socket.on("data", (rates) => {
  console.log("Black Market Rates:", rates);
});

Best Practices

Error Codes

The API uses standard HTTP status codes to show if a request is successful or has an error. These are the common error codes: