> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.
# How to Use Stellar Data
> A developer tutorial for accessing Stellar data with the Mobula API — historical transaction lookups, token liquidity insights, contract interaction data, and real-time WebSocket streams — with live requests, responses, use cases, and guidance on what to use for what.
This tutorial shows how to access Stellar data through the Mobula API — REST endpoints, real-time WebSocket streams, and the TypeScript SDK — across four common needs: **historical transaction lookups**, **token liquidity insights**, **contract interaction data**, and **live market streams**. Every example is a live Stellar request, and [MTT](https://mtt.gg) (open source) renders it all live.
### What you can build
* **Trading bots & terminals** — stream live trades and market depth, then execute off your own signals.
* **Portfolio & tax tools** — reconstruct an account's full history and current holdings.
* **Analytics dashboards** — track liquidity, volume, and holder distribution per market.
* **Price & liquidity alerts** — subscribe to streams and react to moves as ledgers close.
* **New-launch monitors** — surface newly created Stellar pairs the moment they're indexed and move first.
* **Telegram & Discord bots** — forward live trades, price moves, and new pairs straight to a channel.
* **Compliance & reconciliation** — resolve any transfer or swap by transaction hash.
### What you'll need
1. A Stellar asset (`CODE:ISSUER`), a transaction hash, or a `G…` account.
2. The chain identifier `stellar:stellar` (mainnet) or `stellar:testnet`.
3. An API key from the [Dashboard](https://admin.mobula.io).
**Base URLs & keys.** The REST examples below use `https://api.mobula.io` and also run **without a key** on `https://demo-api.mobula.io` for quick evaluation. WebSocket streams always require an API key in the `authorization` field.
### What Stellar supports
Mobula indexes Stellar on **mainnet** (`stellar:stellar`) and **testnet** (`stellar:testnet`), covering tokens, transfers, DEX markets (Aquarius, Soroswap, and the classic AMM), and wallet portfolios. Swap quote/execution routing and NFT holdings are not covered.
Full per-network reference — chain identifiers, address formats, and every supported endpoint:
* **[Stellar (mainnet)](/blockchains/stellar)**
* **[Stellar Testnet](/blockchains/stellar-testnet)**
### What to use for what
| I want to… | Endpoint |
| ------------------------------------------------------ | -------------------------------- |
| Look up one swap/transaction by hash | `GET /api/2/token/trade` |
| Get a token's trade history | `GET /api/2/token/trades` |
| Get an account's full transaction ledger | `GET /api/1/wallet/transactions` |
| See per-market liquidity, reserves & volume | `GET /api/2/token/markets` |
| Get a token's liquidity & market cap | `GET /api/1/metadata` |
| Get decoded account activity (transfers, swaps, vault) | `GET /api/2/wallet/activity` |
| Stream live trades as ledgers close | `WSS fast-trade` |
| Stream live pool price, volume & liquidity | `WSS market-details` |
| Stream live token price & stats | `WSS token-details` |
| Stream real-time OHLCV candles | `WSS ohlcv` |
| Discover newly launched Stellar pairs | `WSS pulse-v2` |
***
## 1. Historical transaction lookups
Use these when you need to resolve a specific transaction, reconstruct a token's trade timeline, or pull an account's full history. Add `limit` (and `offset`) to page through large result sets.
**Look up a single swap by transaction hash** — for support, compliance or reconciliation:
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/token/trade?blockchain=stellar:stellar&transactionHash=84ce022d070cf38a1a4921cdbde9195206ea12c6fd6d2b2b673e74256f78ea3d"
```
```json theme={null}
{
"data": {
"type": "buy",
"baseTokenAmount": 964.8612501,
"baseTokenAmountUSD": 166.02,
"quoteTokenAmount": 167.2260013,
"date": 1785302032000,
"swapSenderAddress": "GCLN4HAD2UPYTQ5WR4RMCHCG5F5XZV77HX7BA7PDPZ7NFEBM4KR56KVR",
"blockchain": "Stellar",
"transactionHash": "84ce022d070cf38a1a4921cdbde9195206ea12c6fd6d2b2b673e74256f78ea3d",
"marketAddress": "CBRUQ7I6C6OGHMDYWD6XQUZFB6KJ3LLPNE34EPKSPFZ2YMBJ2GIWYYZ7"
}
}
```
**Page a token's trade history** — newest first:
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/token/trades?chainId=stellar:stellar&address=AQUA:GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA"
```
**Pull an account's transaction ledger** — the full history for a `G…` account:
```bash theme={null}
curl -X GET "https://api.mobula.io/api/1/wallet/transactions?wallet=GDHF3HIKWM5KJAVLZBSZWUFDOEOT7IBMY22UXG4QBE326O354INLPAND&blockchains=stellar:stellar"
```
```json theme={null}
{
"data": {
"transactions": [
{
"hash": "3f166266f158e1973cff265b891bba28bf4975a4b3e3a9d03c5c4274757a03a3",
"from": "GDHF3HIKWM5KJAVLZBSZWUFDOEOT7IBMY22UXG4QBE326O354INLPAND",
"to": "GAA23STAFIH3D24GT3AKKL4TPK44WEUBH3JF4OPMLN777XQ4EHTHCHIS",
"type": "native",
"amount": 9224.76107,
"block_number": 63698663,
"timestamp": 1785305171000,
"blockchain": "Stellar"
}
]
}
}
```
***
## 2. Token liquidity insights
Use these to rank venues by depth, monitor liquidity migrations across DEXes, or screen out thin pools.
**List an asset's markets** — reserves, 24h volume and price per venue (Aquarius, Soroswap, classic AMM):
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/token/markets?blockchain=stellar:stellar&address=AQUA:GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA"
```
```json theme={null}
{
"data": [
{
"exchange": { "name": "Aquarius" },
"type": "aquarius-concentrated",
"address": "CBRUQ7I6C6OGHMDYWD6XQUZFB6KJ3LLPNE34EPKSPFZ2YMBJ2GIWYYZ7",
"blockchain": "Stellar",
"liquidityUSD": 89861.27,
"volume24hUSD": 9743.39,
"trades24h": 50,
"priceUSD": 0.0003414966853920328,
"latestTradeDate": "2026-07-29T06:08:37.000Z"
}
]
}
```
Each market entry also carries bucketed volume, trade and trader counts (`1min`…`24h`), price-change percentages, fees paid and holder-distribution metrics.
**Get token-level liquidity & market cap** — a single aggregated figure:
```bash theme={null}
curl -X GET "https://api.mobula.io/api/1/metadata?asset=AQUA:GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA&blockchain=stellar:stellar"
```
```json theme={null}
{
"data": { "name": "Aquarius", "symbol": "AQUA", "price": 0.000338, "liquidity": 1086674.84, "market_cap": 12147718.70 }
}
```
***
## 3. Contract interaction data
Use this to build an account activity timeline mixing classic payments and Soroban contract calls, or to attribute value flows to specific contracts and counterparties.
**Fetch decoded account activity** — transfers, swaps and vault operations per transaction:
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/wallet/activity?wallet=GDHF3HIKWM5KJAVLZBSZWUFDOEOT7IBMY22UXG4QBE326O354INLPAND&blockchains=stellar:stellar"
```
```json theme={null}
{
"data": [
{
"chainId": "stellar:stellar",
"txHash": "3f166266f158e1973cff265b891bba28bf4975a4b3e3a9d03c5c4274757a03a3",
"txDateIso": "2026-07-29T06:06:11.000Z",
"txBlockNumber": 63698663,
"txIndex": 111,
"actions": [
{
"model": "transfer",
"transferType": "NATIVE_OUT",
"transferAmount": 9224.76107,
"transferFromAddress": "GDHF3HIKWM5KJAVLZBSZWUFDOEOT7IBMY22UXG4QBE326O354INLPAND",
"transferToAddress": "GAA23STAFIH3D24GT3AKKL4TPK44WEUBH3JF4OPMLN777XQ4EHTHCHIS",
"transferAsset": { "symbol": "XLM", "decimals": 7 }
}
]
}
]
}
```
Each transaction's `actions` array is a decoded view of the interaction: `transfer` (value movements), swap (DEX trades) and vault (deposit/withdraw) models. Transaction-level fields (`txBlockNumber` = ledger sequence, `txIndex` = application order) let you order and reconcile activity exactly as it appears on-chain.
***
## 4. Live market streams
Use these to power live charts, trading terminals, and price or liquidity alerts — updates are pushed as ledgers close, so you never poll.
All Stellar markets and tokens stream over `wss://api.mobula.io`; pass `blockchain: "stellar:stellar"` in the subscribe payload. Every subscribe payload must include your API key in the `authorization` field — streams reject unauthenticated connections.
**Connect and subscribe:**
```javascript theme={null}
const ws = new WebSocket('wss://api.mobula.io');
ws.onopen = () => ws.send(JSON.stringify(subscribe)); // any payload below
ws.onmessage = (e) => console.log(JSON.parse(e.data));
```
| Stream | `type` | Delivers | Docs |
| -------------- | ---------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
| Fast Trades | `fast-trade` | Each swap, pushed as its ledger closes | [Reference](/indexing-stream/stream/websocket/wss-fast-trades) |
| Market Details | `market-details` | Live pool price, volume and liquidity | [Reference](/indexing-stream/stream/websocket/wss-market-details) |
| Token Details | `token-details` | Live token price and market stats | [Reference](/indexing-stream/stream/websocket/wss-token-details) |
| OHLCV | `ohlcv` | Real-time candles | [Reference](/indexing-stream/stream/websocket/ohlcv-stream) |
| Pulse | `pulse-v2` | Newly created and trending Stellar pairs | [Reference](/indexing-stream/stream/websocket/pulse-stream-v2-pool-based) |
**Subscribe to live trades on a Stellar market:**
```json theme={null}
{
"type": "fast-trade",
"authorization": "YOUR-API-KEY",
"payload": {
"assetMode": false,
"items": [
{ "blockchain": "stellar:stellar", "address": "CBRUQ7I6C6OGHMDYWD6XQUZFB6KJ3LLPNE34EPKSPFZ2YMBJ2GIWYYZ7" }
]
}
}
```
**Subscribe to live market details for a Stellar pool:**
```json theme={null}
{
"type": "market-details",
"authorization": "YOUR-API-KEY",
"payload": {
"pools": [
{ "blockchain": "stellar:stellar", "address": "CBRUQ7I6C6OGHMDYWD6XQUZFB6KJ3LLPNE34EPKSPFZ2YMBJ2GIWYYZ7" }
]
}
}
```
Token Details and OHLCV follow the same connection pattern — set `blockchain` to `stellar:stellar` and see each stream's reference for its payload fields.
**Be a first mover — stream newly launched Stellar pairs:**
Scope Pulse to `stellar:stellar` and sort by `created_at` to receive new pairs the moment they're indexed.
```json theme={null}
{
"type": "pulse-v2",
"authorization": "YOUR-API-KEY",
"payload": {
"views": [
{
"name": "new-stellar-pairs",
"chainId": ["stellar:stellar"],
"sortBy": "created_at",
"sortOrder": "desc",
"limit": 50
}
]
}
}
```
***
## 5. Build with the SDK
The [`@mobula_labs/sdk`](https://www.npmjs.com/package/@mobula_labs/sdk) wraps every endpoint above with typed methods and defaults to `demo-api.mobula.io`, so it works without a key for evaluation.
```bash theme={null}
npm install @mobula_labs/sdk
```
```typescript theme={null}
import { MobulaClient } from '@mobula_labs/sdk';
const client = new MobulaClient({ apiKey: 'YOUR-API-KEY' });
// Stellar token markets — liquidity, volume and price per venue
const markets = await client.fetchTokenMarkets({
blockchain: 'stellar:stellar',
address: 'CAUP7NFABXE5TJRL3FKTPMWRLC7IAXYDCTHQRFSCLR5TMGKHOOQO772J', // XSOLVBTC
});
// → [{ exchange: { name: 'Aquarius' }, liquidityUSD: 10472431.6, priceUSD: 63338.23, ... }]
```
The same typed methods power **[MTT](https://mtt.gg)** — Mobula's open-source trading terminal and a full reference implementation that renders Stellar tokens live:
mtt.gg/token/stellar:stellar/CAUP7NFA…772J — live chart, trades, liquidity and holders, all served by the endpoints on this page.
Source: [github.com/MobulaFi/MTT](https://github.com/MobulaFi/MTT).
***
## Use cases in practice
Each use case is just a few of the calls above combined. A few worked examples:
**Portfolio tracker** — an account's current holdings plus its decoded activity feed:
```bash theme={null}
# 1) Balances
curl "https://api.mobula.io/api/2/wallet/holdings?wallet=GDHF3HIK…PAND&blockchains=stellar:stellar"
# 2) Decoded activity (transfers, swaps, vault)
curl "https://api.mobula.io/api/2/wallet/activity?wallet=GDHF3HIK…PAND&blockchains=stellar:stellar"
```
**Token dashboard** — valuation, per-venue liquidity, and recent trades for one token:
```bash theme={null}
# 1) Market cap + aggregate liquidity
curl "https://api.mobula.io/api/1/metadata?asset=AQUA:GBNZ…AQUA&blockchain=stellar:stellar"
# 2) Liquidity per venue (Aquarius, Soroswap, classic AMM)
curl "https://api.mobula.io/api/2/token/markets?blockchain=stellar:stellar&address=AQUA:GBNZ…AQUA"
# 3) Recent trades
curl "https://api.mobula.io/api/2/token/trades?chainId=stellar:stellar&address=AQUA:GBNZ…AQUA"
```
**New-launch monitor (first mover)** — stream freshly created pairs, then pull each one's liquidity to filter:
```text theme={null}
1) Subscribe to pulse-v2 scoped to stellar:stellar, sorted by created_at desc (see §4)
2) For each new market address it pushes:
GET /api/2/token/markets?blockchain=stellar:stellar&address=
3) Act on the pairs that clear your liquidity / volume threshold
```
**Live trading terminal** — snapshot with REST, then keep it live over a stream:
```text theme={null}
1) GET /api/2/token/markets → initial price, liquidity, trades
2) Subscribe to fast-trade + market-details for the pool (see §4)
3) Apply each pushed update to your local state as ledgers close
```
**Telegram bot** — push new-pair or price alerts to a channel:
```text theme={null}
1) Subscribe to pulse-v2 (new pairs) or fast-trade (price/trades) over WSS (see §4)
2) On each pushed update, call the Telegram Bot API sendMessage to post it
```
See the full build in **[Build a Telegram Buy Bot](/guides/build-telegram-buy-bot)** — the same pattern, pointed at `stellar:stellar`.
### Need Help?
Our support team is available to assist with your queries or integration issues.
Telegram
Slack
Discord
Email