> ## 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.

# Complete Stellar Swap & Transfer Stream Guide

> A developer guide to the Stellar multi-events WebSocket stream — copy-paste subscription examples for streaming swaps and transfers: by pool, by wallet, by token, by venue, and amount thresholds like swaps over $100 on a specific pool.

### 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](/indexing-stream/stream/filters).

### 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

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

Response:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{ "eq": ["poolAddress", "CCNXGPE4AQCSNEBZO3XJDKKDI3CRLYMVS6UWBBTVDLALLWMJEXBORQ2A"] }
```

### Swaps over \$100 on one pool

`and` an amount threshold onto the pool:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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

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

Response:

```json theme={null}
{
  "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.

<Warning>
  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**.
</Warning>

### A wallet's transfers, both directions

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

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"
  }
}
```

<Note>
  **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.
</Note>

***

## 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:

```typescript theme={null}
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](/guides/build-telegram-buy-bot) for the pattern.
* **Reference** — [Swaps stream](/indexing-stream/stream/websocket/multi-events-swaps-stream), [Transfers stream](/indexing-stream/stream/websocket/multi-events-transfers-stream), [filters](/indexing-stream/stream/filters), [How the Stellar indexer works](/guides/stellar-indexer), [How to use Stellar data](/guides/how-to-use-stellar-data).