Complete Stellar Swap & Transfer Stream Guide

Endpoint & subscription


Endpoint	`wss://stream-stellar-prod.mobula.io/`
Chains	`stellar:stellar`· `stellar:testnet`
Events	`swap`, `transfer`, `swap-enriched`

Connect, send a subscription, get an acknowledgment ("event": "subscribed"), then matching events as ledgers close. Ignore {"event":"ping"} keepalives, and unsubscribe with {"type":"unsubscribe","authorization":"YOUR_API_KEY","payload":{"subscriptionId":"..."}}. Multiple subscriptions share one socket; the subscriptionId echoed on every frame routes each event back to the subscription that matched it. Filters run server-side; operators are eq, neq, lt, lte, gt, gte, in, nested with and / or — see the filters reference.

Stellar address forms

Five address forms appear in the frames, and casing matters in filters:

Form	Example	Used for
`G…` (uppercase)	`GDEDWJFWOM226RNH…`	Accounts — senders, receivers
`CODE:ISSUER` (uppercase)	`AQUA:GBNZILSTVQZ4R7IK…AQUA`	Classic assets
`C…` (uppercase)	`CCNXGPE4AQCSNEBZ…`	Soroban contracts — tokens and Soroswap/Aquarius pools
`lp:<hex>` (lowercase)	`lp:9babe6bb11f6464b…`	Classic AMM pools
`0xeeee…eeee`	`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`	Native XLM sentinel

Swaps

Stream every swap

{
  "type": "stream",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "name": "StellarSwaps",
    "chainIds": ["stellar:stellar"],
    "events": ["swap"],
    "subscriptionId": "stellar-swaps"
  }
}

Response:

{
  "data": {
    "type": "swap",
    "blockHeight": "63887174",
    "date": "2026-08-10T12:00:59.000Z",
    "transactionHash": "ef4381b53d6be3f9b885999cf8034f10c013028f9cdcd767642616d12930c1cf",
    "transactionSenderAddress": "GBGRBCUB6L7LH4JQ6EPDP7REH2DDACMCUQI76M3P6DM52QWU2Z5LIEVW",
    "poolAddress": "lp:df3f4b516732ba2a7aa5b2b365d43591e62eb5d7900b4e85a070324ce3312747",
    "poolType": "stellar-classic-amm",
    "addressToken0": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "addressToken1": "EITG:GAESFYN2EJDELM56RMDHS3R7GGUT7M5J64ZRINRAHGEC7CWQKOD22EQM",
    "amount0": 0.0021629,
    "amount1": -1044.8527516,
    "rawAmount0": "21629",
    "rawAmount1": "-10448527516",
    "amountUSD": 0.00035,
    "priceUSDToken0": 0.16362,
    "priceUSDToken1": 3.387e-7,
    "swapType": "REGULAR",
    "transactionSwapsCount": 3
  },
  "chainId": "stellar:stellar",
  "subscriptionId": "stellar-swaps"
}

Reading a swap: amount0/amount1 are decimal-adjusted deltas — positive is what the trader paid into the pool, negative is what they received — with rawAmount0/rawAmount1 as the on-ledger integers and amountUSD/priceUSDToken0/priceUSDToken1 pre-computed. transactionSenderAddress is the trading account, and transactionSwapsCount tells you how many legs the transaction has (path payments produce several).

Swaps on one pool

Classic AMM market — lowercase lp: form:

{
  "type": "stream",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "name": "PoolSwaps",
    "chainIds": ["stellar:stellar"],
    "events": ["swap"],
    "filters": { "eq": ["poolAddress", "lp:9babe6bb11f6464b090e8edc7633e60a016b35a3ad10463cf720697bfc284b6b"] },
    "subscriptionId": "pool-swaps"
  }
}

Soroswap and Aquarius markets are C… contracts — same filter, uppercase address:

{ "eq": ["poolAddress", "CCNXGPE4AQCSNEBZO3XJDKKDI3CRLYMVS6UWBBTVDLALLWMJEXBORQ2A"] }

Swaps over $100 on one pool

and an amount threshold onto the pool:

{
  "type": "stream",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "name": "BigPoolSwaps",
    "chainIds": ["stellar:stellar"],
    "events": ["swap"],
    "filters": {
      "and": [
        { "eq": ["poolAddress", "lp:9babe6bb11f6464b090e8edc7633e60a016b35a3ad10463cf720697bfc284b6b"] },
        { "gte": ["amountUSD", 100] }
      ]
    },
    "subscriptionId": "big-pool-swaps"
  }
}

Drop the pool clause to get every swap over $100 network-wide — a one-line whale feed.

Swaps by venue

All classic-AMM trades — works the same with soroswap, aquarius, aquarius-stable, aquarius-concentrated:

{
  "type": "stream",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "name": "ClassicAmmSwaps",
    "chainIds": ["stellar:stellar"],
    "events": ["swap"],
    "filters": { "eq": ["poolType", "stellar-classic-amm"] },
    "subscriptionId": "classic-amm-swaps"
  }
}

A wallet’s trades

Swaps identify the trader as transactionSenderAddress:

{
  "type": "stream",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "name": "WalletSwaps",
    "chainIds": ["stellar:stellar"],
    "events": ["swap"],
    "filters": { "eq": ["transactionSenderAddress", "GDEDWJFWOM226RNH765BDLK4BTKYYJZQHI7EAXK4DMPYCC3RWBKTHJ2J"] },
    "subscriptionId": "wallet-swaps"
  }
}

Transfers

Stream every transfer

{
  "type": "stream",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "name": "StellarTransfers",
    "chainIds": ["stellar:stellar"],
    "events": ["transfer"],
    "subscriptionId": "stellar-transfers"
  }
}

Response:

{
  "data": {
    "type": "transfer",
    "blockNumber": 63887147,
    "date": "2026-08-10T11:58:27.000Z",
    "transactionHash": "3b1a5b55dd2d34c6aa9536afd284035b35c5ad639d2a164ce7f086be2494bed1",
    "transactionFrom": "GAOSARKBOOZXN3QOZQ7QJZIVDS5NU6KUFE4FINAJQYIES3KKCHL3RL37",
    "transactionTo": "GDEDWJFWOM226RNH765BDLK4BTKYYJZQHI7EAXK4DMPYCC3RWBKTHJ2J",
    "from": "GDEDWJFWOM226RNH765BDLK4BTKYYJZQHI7EAXK4DMPYCC3RWBKTHJ2J",
    "to": "lp:4b7890d7699dbfbc44d581ddb9c3baa0b65e3aeb07f093b76ec7ff6c9ec2cd60",
    "contract": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "amount": "10000000",
    "transactionFees": "100",
    "amountUSD": 0
  },
  "chainId": "stellar:stellar",
  "subscriptionId": "stellar-transfers"
}

Reading a transfer: transactionFrom/transactionTo are the envelope-level source and destination accounts; from/to are the transfer leg itself — a G… account, a C… contract, an lp: pool, or the zero address on mints and burns. contract is the asset moved and amount is the raw on-ledger integer — divide by 10⁷ for XLM and classic assets. transactionFees is in stroops.

Transfers cover every token movement on the network — including mints, burns and pool deposits — and amountUSD is 0 whenever the asset has no reliable price. Put USD thresholds on swaps and raw-amount thresholds on transfers.

A wallet’s transfers, both directions

Transfers filter on the envelope fields — or the two directions:

{
  "type": "stream",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "name": "WalletTransfers",
    "chainIds": ["stellar:stellar"],
    "events": ["transfer"],
    "filters": {
      "or": [
        { "eq": ["transactionFrom", "GDEDWJFWOM226RNH765BDLK4BTKYYJZQHI7EAXK4DMPYCC3RWBKTHJ2J"] },
        { "eq": ["transactionTo",   "GDEDWJFWOM226RNH765BDLK4BTKYYJZQHI7EAXK4DMPYCC3RWBKTHJ2J"] }
      ]
    },
    "subscriptionId": "wallet-transfers"
  }
}

All movements of one token

Native XLM via the sentinel — or any classic asset by its CODE:ISSUER:

{
  "type": "stream",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "name": "XlmTransfers",
    "chainIds": ["stellar:stellar"],
    "events": ["transfer"],
    "filters": { "eq": ["contract", "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"] },
    "subscriptionId": "xlm-transfers"
  }
}

Whale transfers — 1,000+ XLM

Raw units: 1,000 XLM = 10¹⁰ stroops. In live testing this caught a 22,500 XLM movement within seconds:

{
  "type": "stream",
  "authorization": "YOUR_API_KEY",
  "payload": {
    "name": "XlmWhales",
    "chainIds": ["stellar:stellar"],
    "events": ["transfer"],
    "filters": {
      "and": [
        { "eq": ["contract", "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"] },
        { "gte": ["amount", 10000000000] }
      ]
    },
    "subscriptionId": "xlm-whales"
  }
}

Filter on the right wallet field per event type. It’s transactionSenderAddress on swaps but transactionFrom/transactionTo on transfers — they are not interchangeable. The transfer leg fields from/to (and swapSenderAddress on swaps) appear in every frame for client-side use but do not match in server-side filters.

Putting it together — a pool watcher

Big-swap alerts on one market plus an XLM whale feed, on a single socket. Runs as-is with Node 22+ or Bun:

const API_KEY = "YOUR_API_KEY";
const POOL = "lp:9babe6bb11f6464b090e8edc7633e60a016b35a3ad10463cf720697bfc284b6b";
const XLM = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";

function connect(retryMs = 1000) {
  const ws = new WebSocket("wss://stream-stellar-prod.mobula.io");

  ws.onopen = () => {
    retryMs = 1000;
    ws.send(JSON.stringify({
      type: "stream", authorization: API_KEY,
      payload: {
        name: "BigPoolSwaps", chainIds: ["stellar:stellar"], events: ["swap"],
        filters: { and: [{ eq: ["poolAddress", POOL] }, { gte: ["amountUSD", 100] }] },
        subscriptionId: "big-pool-swaps",
      },
    }));
    ws.send(JSON.stringify({
      type: "stream", authorization: API_KEY,
      payload: {
        name: "XlmWhales", chainIds: ["stellar:stellar"], events: ["transfer"],
        filters: { and: [{ eq: ["contract", XLM] }, { gte: ["amount", 10000000000] }] },
        subscriptionId: "xlm-whales",
      },
    }));
  };

  ws.onmessage = (msg) => {
    const frame = JSON.parse(String(msg.data));
    if (frame.event === "ping") return;
    if (frame.event === "subscribed") return console.log(`✓ ${frame.subscriptionId}`);
    const d = frame.data;
    if (!d) return;

    const sym = (a) => a === XLM ? "XLM" : String(a).split(":")[0];
    if (d.type === "swap") {
      const [paid, got] = d.amount0 > 0
        ? [[d.amount0, d.addressToken0], [-d.amount1, d.addressToken1]]
        : [[d.amount1, d.addressToken1], [-d.amount0, d.addressToken0]];
      console.log(`SWAP $${d.amountUSD.toFixed(0)}: ${paid[0]} ${sym(paid[1])} → ${got[0]} ${sym(got[1])} on ${d.poolType}  ledger ${d.blockHeight}`);
    } else if (d.type === "transfer") {
      console.log(`WHALE ${(Number(d.amount) / 1e7).toLocaleString()} XLM  ${d.transactionFrom.slice(0, 6)}… → ${d.transactionTo.slice(0, 6)}…  ${d.transactionHash.slice(0, 8)}…`);
    }
  };

  ws.onclose = () => setTimeout(() => connect(Math.min(retryMs * 2, 30_000)), retryMs);
}
connect();

✓ big-pool-swaps
✓ xlm-whales
SWAP $669: 4089 XLM → 8543 USDC on stellar-classic-amm  ledger 63887201
WHALE 22,500 XLM  GAOSAR… → GDEDWJ…  3b1a5b55…

Going further

Testnet — same endpoint, chainIds: ["stellar:testnet"].
Alerting — pipe the handler into a Telegram or Discord webhook; see Build a Telegram buy bot for the pattern.
Reference — Swaps stream, Transfers stream, filters, How the Stellar indexer works, How to use Stellar data.

Overview

Getting Started

Guides

Blog

Complete Stellar Swap & Transfer Stream Guide

Endpoint & subscription

Stellar address forms

Swaps

Stream every swap

Swaps on one pool

Swaps over $100 on one pool

Swaps by venue

A wallet’s trades

Transfers

Stream every transfer

A wallet’s transfers, both directions

All movements of one token

Whale transfers — 1,000+ XLM

Putting it together — a pool watcher

Going further

​Endpoint & subscription

​Stellar address forms

​Swaps

​Stream every swap

​Swaps on one pool

​Swaps over $100 on one pool

​Swaps by venue

​A wallet’s trades

​Transfers

​Stream every transfer

​A wallet’s transfers, both directions

​All movements of one token

​Whale transfers — 1,000+ XLM

​Putting it together — a pool watcher

​Going further

Endpoint & subscription

Stellar address forms

Swaps

Stream every swap

Swaps on one pool

Swaps over $100 on one pool

Swaps by venue

A wallet’s trades

Transfers

Stream every transfer

A wallet’s transfers, both directions

All movements of one token

Whale transfers — 1,000+ XLM

Putting it together — a pool watcher

Going further