StellarKit API 🚀

English 🇺🇸 | Français 🇫🇷 | Español 🇪🇸

A developer utility REST API for the Stellar blockchain — built with Express.js and the official Stellar SDK.

StellarKit API wraps the Stellar Horizon API into clean, developer-friendly REST endpoints. It helps developers building on Stellar quickly access fee estimates, account data, transaction history, network status, and asset metadata — without having to read through raw Horizon responses.

---

✨ Features

• 📊 Network Status — Latest ledger info, base fee, protocol version
• 💸 Fee Estimation — Economy / Standard / Priority fee tiers for any operation count
• 👤 Account Info — Balances (XLM + all assets), signers, thresholds, spendable balance
• 📜 Transaction History — Paginated transactions and operations per account
• 🪙 Asset Metadata — Stats for any Stellar asset, plus multi-issuer search
• 🛡️ Production-ready — Rate limiting, helmet security headers, centralised error handling
• ✅ Tested — Jest test suite with coverage

---

🚀 Getting Started

Prerequisites

• Node.js >= 18
• npm >= 9

Installation

git clone https://github.com/stellarkit-lab-devtools/stellarkit-api.git
cd stellarkit-api
npm install
cp .env.example .env

Configuration

Edit .env:

STELLAR_NETWORK=testnet     # or "mainnet"
PORT=3000

Run

# Development (auto-reload)
npm run dev

# Production
npm start

The API will be available at http://localhost:3000.

---

📡 API Endpoints

GET /

Returns the full list of available endpoints.

---

GET /health

Service health check.

Response:

{
  "success": true,
  "data": {
    "status": "ok",
    "service": "StellarKit API",
    "version": "1.0.0",
    "network": "testnet"
  }
}

---

GET /network-status

Returns the latest ledger info, fees, and protocol version.

Response:

{
  "success": true,
  "data": {
    "network": "testnet",
    "latestLedger": {
      "sequence": 123456,
      "closedAt": "2024-07-01T12:00:00Z",
      "transactionCount": 42,
      "operationCount": 89
    },
    "fees": {
      "baseFeeInStroops": 100,
      "baseFeeInXLM": "0.0000100"
    },
    "protocol": { "version": 21 }
  }
}

---

GET /fee-estimate

Returns Economy / Standard / Priority fee tiers based on live network stats.

Query params:

Param	Type	Default	Description
operations	number	1	Number of operations in your transaction

Example:

GET /fee-estimate?operations=3

Response:

{
  "success": true,
  "data": {
    "operationCount": 3,
    "perOperation": {
      "economy":  { "stroops": 100, "xlm": "0.0000100" },
      "standard": { "stroops": 200, "xlm": "0.0000200" },
      "priority": { "stroops": 500, "xlm": "0.0000500" }
    },
    "totalFee": {
      "economy":  { "stroops": 300, "xlm": "0.0000300" },
      "standard": { "stroops": 600, "xlm": "0.0000600" },
      "priority": { "stroops": 1500, "xlm": "0.0001500" }
    }
  }
}

---

GET /account/:id

Returns full account details for a Stellar public key.

Example:

GET /account/GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN

Response:

{
  "success": true,
  "data": {
    "accountId": "GAAZI4...",
    "sequence": "12345678",
    "xlm": {
      "balance": "100.0000000",
      "minimumBalance": "1.0000000",
      "spendableBalance": "99.0000000"
    },
    "assets": [...],
    "signers": [...],
    "flags": {...}
  }
}

---

GET /transactions/:id

Returns paginated transaction history for an account.

Query params:

Param	Type	Default	Description
limit	number	10	Number of results (max 200)
order	string	desc	asc or desc
cursor	string	—	Pagination cursor from previous response

---

GET /transactions/:id/operations

Returns paginated operation history for an account. Same query params as above.

---

GET /asset/:code/:issuer

Returns metadata and statistics for a specific Stellar asset.

Example:

GET /asset/USDC/GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN

---

GET /asset/search?code=:code

Searches for all assets with a given code across all issuers.

Example:

GET /asset/search?code=USDC

---

📡 Streaming & WebSockets

WS /stream/ledgers

Establishes a live, real-time WebSocket connection to stream Stellar ledger updates. As new ledgers are closed on the Stellar blockchain, the API receives them via the Stellar Horizon SDK subscription, parses them, and immediately broadcasts them to connected WebSocket clients.

Client Connection Example (Vanilla JS)

const ws = new WebSocket('ws://localhost:3000/stream/ledgers');

ws.onopen = () => {
  console.log('Connected to StellarKit ledger stream!');
};

ws.onmessage = (event) => {
  const ledger = JSON.parse(event.data);
  console.log('New ledger closed:', ledger);
  // Example output:
  // {
  //   "sequence": 51234567,
  //   "closedAt": "2026-05-26T20:15:00Z",
  //   "baseFee": 100,
  //   "transactionCount": 54
  // }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('WebSocket connection closed.');
};

---

🧪 Running Tests

npm test

Tests use Jest + Supertest. Coverage report is generated at coverage/.

---

🤝 Contributing

Contributions are very welcome! This project participates in the Stellar Wave Program on Drips — you can earn rewards for solving open issues.

To contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit your changes: git commit -m "feat: add your feature"
4. Push and open a Pull Request

Please read CONTRIBUTING.md before submitting.

---

📁 Project Structure

stellarkit-api/
├── scripts/
│   └── ws-client-demo.js  # Runnable CLI demo for real-time ledger stream
├── src/
│   ├── config/
│   │   └── stellar.js         # Stellar SDK + Horizon setup
│   ├── middleware/
│   │   ├── errorHandler.js    # Centralised error formatting
│   │   └── rateLimiter.js     # Rate limiting
│   ├── routes/
│   │   ├── account.js         # /account endpoints
│   │   ├── asset.js           # /asset endpoints
│   │   ├── feeEstimate.js     # /fee-estimate endpoint
│   │   ├── networkStatus.js   # /network-status endpoint
│   │   └── transactions.js    # /transactions endpoints
│   ├── utils/
│   │   ├── response.js        # Response helpers
│   │   └── validators.js      # Input validation helpers
│   ├── index.js               # App entry point
│   └── websocket.js           # WebSocket stream handler
├── tests/
│   ├── api.test.js
│   └── websocket.test.js      # WebSocket stream integration tests
├── .env.example
├── package.json
└── README.md

---

🌐 Stellar Resources

• Stellar Developers Portal
• Stellar JavaScript SDK
• Horizon API Reference
• Stellar Discord
• Stellar Wave Program

---

📄 License

MIT