Transaction Lifecycle

This guide walks through every step of a swap transaction — from requesting a quote to receiving on-chain confirmation — with error handling and edge cases at each step.

---

Overview

A complete swap involves three services and twelve distinct steps:

Client          arb-algo              mx-relayer          MultiversX
  │                │                     │                    │
  │ 1. GET /quote  │                     │                    │
  │───────────────▶│                     │                    │
  │◀───────────────│                     │                    │
  │  txData, amountOutMin               │                    │
  │                                     │                    │
  │ 2. subscribe tx-status/{hash}       │                    │
  │────────────────────────────────────▶│                    │
  │                                     │                    │
  │ 3. relay action                     │                    │
  │────────────────────────────────────▶│                    │
  │                              4. validate + co-sign       │
  │                                     │ 5. P2P broadcast   │
  │                                     │───────────────────▶│
  │                                     │           6. execute tx
  │                                     │◀───────────────────│
  │                              7. SaveBlock from notifier  │
  │                                     │                    │
  │ 8. tx-status event                  │                    │
  │◀────────────────────────────────────│                    │

---

Step-by-Step Guide

Step 1: Get a swap quote

Call the arb-algo quote endpoint with the tokens and amount to swap. The response includes txData (the ready-to-use transaction payload) and amountOutMin (the slippage-protected minimum output).

async function getQuote({ from, to, amountIn, slippage = 0.01 }) {
  const params = new URLSearchParams({ from, to, amountIn, slippage });
  const res = await fetch(`https://swap.xoxno.com/api/v1/quote?${params}`);

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`Quote failed: ${err.error}`);
  }

  return res.json();
}

Error handling at this step:

Error	Cause	Action
unknown token_in	Token identifier is not recognized	Check token format (TICKER-hexcode); use pair-config to validate
routing failed: no path between tokens	No liquidity path exists between the two tokens	Try routing via an intermediate token (e.g., WEGLD) manually
specify either amount_in or amount_out, not both	Both amountIn and amountOut were provided	Provide exactly one
HTTP 429	Rate limit exceeded (100 req/s)	Add backoff

What to extract from the response:

const quote = await getQuote({
  from: 'WEGLD-bd4d79',
  to: 'USDC-c76f1f',
  amountIn: '1000000000000000000'
});

const { txData, amountOutMin, priceImpact } = quote;

Pool state refreshes every 5 seconds. If you hold a quote for more than a few seconds before submitting, on-chain reserves may have moved. The amountOutMin field protects against this: if the actual output falls below this value, the smart contract reverts automatically.

---

Step 2: Connect to the relayer WebSocket

Open a WebSocket connection and wait for it to be ready.

function connectRelayer() {
  return new Promise((resolve, reject) => {
    const ws = new WebSocket('wss://relayer.xoxno.com/ws');

    ws.onopen = () => resolve(ws);
    ws.onerror = (err) => reject(new Error('WebSocket connection failed'));

    // Re-establish ping/pong baseline (relayer sends pings every 30s)
    ws.onclose = () => console.warn('Relayer connection closed');
  });
}

const ws = await connectRelayer();

---

Step 3: Subscribe to gas statistics

Subscribe to gasStats before building the transaction. Use the per-shard percentiles to set a competitive gasPrice — see Gas Optimization for the full strategy.

function subscribeGasStats(ws) {
  return new Promise((resolve) => {
    const stats = new Map(); // shard → data

    ws.addEventListener('message', function handler(event) {
      const msg = JSON.parse(event.data);
      if (msg.type === 'gasStats') {
        stats.set(msg.data.shard, msg.data);
        // Wait until we have at least one shard's data
        if (stats.size >= 1) {
          ws.removeEventListener('message', handler);
          resolve(stats);
        }
      }
    });

    ws.send(JSON.stringify({ action: 'subscribe', topic: 'gasStats' }));
  });
}

const gasStats = await subscribeGasStats(ws);

function getGasPrice(senderShard) {
  const data = gasStats.get(senderShard);
  return data ? data.gasPrice.percentiles.p75 : 1000000000;
}

---

Step 4: Determine relayer address for the sender's shard

Each MultiversX shard has a dedicated relayer wallet. Use the relayer address that matches the sender's shard, and ensure the user signs the transaction with the relayer field present.

const RELAYER_ADDRESSES = {
  0: 'erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h',
  1: 'erd12yxd5phejzw83gn8qh6jfz6q9a0ekyyhkfd3c49r03mxw25l3a5swq3nf7',
  2: 'erd13jxp0yjh7gjvzgrg5mj7e8rzhn5lzcye45l0p6e5996d543r7vrq9e50za'
};

// shard = last byte of public key % 3
function getSenderShard(bech32Address) {
  const decoded = bech32.decode(bech32Address);
  const pubKeyBytes = bech32.fromWords(decoded.words);
  return pubKeyBytes[pubKeyBytes.length - 1] % 3;
}

const senderShard = getSenderShard(senderAddress);
const relayerAddress = RELAYER_ADDRESSES[senderShard];

---

Step 5: Build and sign the transaction

Construct the transaction with the relayer field set before signing. The user must sign after the relayer field is included.

const tx = {
  nonce: accountNonce,          // current nonce from network
  value: '0',                   // EGLD value (0 for ESDT swaps)
  receiver: AGGREGATOR_CONTRACT,
  sender: senderAddress,
  gasPrice: getGasPrice(senderShard),
  gasLimit: 50_000_000,         // use quote.estimatedGasLimit if provided
  data: quote.txData,           // base64 payload from arb-algo
  chainID: '1',
  version: 2,
  relayer: relayerAddress       // must be set BEFORE signing
};

// Sign with user's private key (sdk-wallet or equivalent)
const signature = await userSigner.sign(serializeForSigning(tx));
tx.signature = signature;

The relayer field must be present before the user signs. Signing without it and adding it afterward produces an invalid signature; the relay will be rejected.

---

Step 6: Subscribe to tx-status BEFORE sending

Compute the transaction hash from the signed transaction and subscribe to tx-status/{hash} before sending the relay action. The relayer emits the status event exactly once and never replays it — subscribing after the block finalizes means missing the event.

// txHash is deterministic from the signed transaction object
const txHash = computeTxHash(tx); // from @multiversx/sdk-core

// Subscribe before sending
ws.send(JSON.stringify({
  action: 'subscribe',
  topic: `tx-status/${txHash}`
}));

// Set up a listener
const confirmationPromise = new Promise((resolve, reject) => {
  const ttl = setTimeout(() => {
    reject(new Error('tx-status TTL expired: no confirmation within 60 seconds'));
  }, 60_000);

  ws.addEventListener('message', function handler(event) {
    const msg = JSON.parse(event.data);
    if (msg.type === 'tx-status' && msg.data.hash === txHash) {
      clearTimeout(ttl);
      ws.removeEventListener('message', handler);
      resolve(msg.data);
    }
  });
});

---

Step 7: Send the relay action

ws.send(JSON.stringify({
  action: 'relay',
  requestId: 'swap-001',    // unique per request for correlation
  tx
}));

Wait for the relay acknowledgment (relayer accepted and broadcast the transaction) separately from the tx-status confirmation (transaction executed on-chain):

const relayAck = await new Promise((resolve, reject) => {
  const timeout = setTimeout(() => reject(new Error('Relay acknowledgment timeout')), 15_000);

  ws.addEventListener('message', function handler(event) {
    const msg = JSON.parse(event.data);
    if (msg.action === 'relay' && msg.requestId === 'swap-001') {
      clearTimeout(timeout);
      ws.removeEventListener('message', handler);

      if (msg.status === 'failed') {
        reject(new Error(msg.failed?.[0]?.reason || 'Relay failed'));
      } else {
        resolve(msg);
      }
    }
  });
});

console.log('Transaction broadcast, hash:', relayAck.hashes[0]);

Relay acknowledgment errors:

Error	Cause	Action
invalid relayer address	Wrong relayer for sender's shard	Recalculate shard and select correct address
relayer field missing	Transaction built without relayer field	Rebuild transaction with relayer included
invalid user signature	Signed before adding relayer field	Re-sign with relayer field present
nonce too low	Nonce already used	Fetch current nonce from network and retry
nonce too high	Gap in nonce sequence	Submit earlier nonces first

---

Step 8: Wait for on-chain confirmation

const status = await confirmationPromise;

if (status.status === 'success') {
  console.log('Swap confirmed. Output received.');
} else {
  console.error('Transaction failed on-chain:', status.reason);
  // Common reasons:
  //   "execution failed" + smart contract revert → amountOut < amountOutMin (slippage)
  //   "insufficient funds" → gas limit too low
}

---

Complete Example

The following self-contained example performs all steps in sequence.

import bech32 from 'bech32';
// Assumes @multiversx/sdk-core and @multiversx/sdk-wallet are installed

const AGGREGATOR_CONTRACT = 'erd1qqqqqqqqqqqqqpgqmsgtu8888h0j3nkxvp5kkeydl7hxs00dsq2snk2f5t';

const RELAYER_ADDRESSES = {
  0: 'erd1l0x0n5yxsfcy93gm0vyvx9m9f7cte9h9vuq4am33ugpw3d5r3hvqx6f59h',
  1: 'erd12yxd5phejzw83gn8qh6jfz6q9a0ekyyhkfd3c49r03mxw25l3a5swq3nf7',
  2: 'erd13jxp0yjh7gjvzgrg5mj7e8rzhn5lzcye45l0p6e5996d543r7vrq9e50za'
};

function getSenderShard(bech32Address) {
  const decoded = bech32.decode(bech32Address);
  const pubKeyBytes = bech32.fromWords(decoded.words);
  return pubKeyBytes[pubKeyBytes.length - 1] % 3;
}

async function executeSwap({ senderAddress, senderSigner, accountNonce, from, to, amountIn }) {
  // Step 1: Get quote
  const params = new URLSearchParams({ from, to, amountIn, slippage: '0.01' });
  const quoteRes = await fetch(`https://swap.xoxno.com/api/v1/quote?${params}`);
  if (!quoteRes.ok) throw new Error(`Quote error: ${(await quoteRes.json()).error}`);
  const quote = await quoteRes.json();

  // Step 2: Connect to relayer
  const ws = await new Promise((resolve, reject) => {
    const sock = new WebSocket('wss://relayer.xoxno.com/ws');
    sock.onopen = () => resolve(sock);
    sock.onerror = () => reject(new Error('WebSocket failed'));
  });

  // Step 3: Subscribe to gas stats and wait for first update
  const gasStats = await new Promise((resolve) => {
    const stats = new Map();
    ws.addEventListener('message', function h(e) {
      const msg = JSON.parse(e.data);
      if (msg.type === 'gasStats') {
        stats.set(msg.data.shard, msg.data);
        if (stats.size >= 1) { ws.removeEventListener('message', h); resolve(stats); }
      }
    });
    ws.send(JSON.stringify({ action: 'subscribe', topic: 'gasStats' }));
  });

  // Step 4: Determine relayer address
  const senderShard = getSenderShard(senderAddress);
  const relayerAddress = RELAYER_ADDRESSES[senderShard];
  const shardGasData = gasStats.get(senderShard);
  const gasPrice = shardGasData ? shardGasData.gasPrice.percentiles.p75 : 1_000_000_000;

  // Step 5: Build and sign transaction
  const tx = {
    nonce: accountNonce,
    value: '0',
    receiver: AGGREGATOR_CONTRACT,
    sender: senderAddress,
    gasPrice,
    gasLimit: 50_000_000,
    data: quote.txData,
    chainID: '1',
    version: 2,
    relayer: relayerAddress   // relayer field BEFORE signing
  };
  tx.signature = await senderSigner.sign(serializeForSigning(tx));

  // Step 6: Compute hash and subscribe BEFORE sending
  const txHash = computeTxHash(tx);
  ws.send(JSON.stringify({ action: 'subscribe', topic: `tx-status/${txHash}` }));

  const confirmationPromise = new Promise((resolve, reject) => {
    const ttl = setTimeout(() => reject(new Error('tx-status TTL expired (60s)')), 60_000);
    ws.addEventListener('message', function h(e) {
      const msg = JSON.parse(e.data);
      if (msg.type === 'tx-status' && msg.data?.hash === txHash) {
        clearTimeout(ttl);
        ws.removeEventListener('message', h);
        resolve(msg.data);
      }
    });
  });

  // Step 7: Send relay action
  const requestId = `swap-${Date.now()}`;
  const relayAck = await new Promise((resolve, reject) => {
    const timeout = setTimeout(() => reject(new Error('Relay ack timeout')), 15_000);
    ws.addEventListener('message', function h(e) {
      const msg = JSON.parse(e.data);
      if (msg.action === 'relay' && msg.requestId === requestId) {
        clearTimeout(timeout);
        ws.removeEventListener('message', h);
        if (msg.status === 'failed') reject(new Error(msg.failed?.[0]?.reason ?? 'Relay failed'));
        else resolve(msg);
      }
    });
    ws.send(JSON.stringify({ action: 'relay', requestId, tx }));
  });

  console.log('Broadcast confirmed, tx hash:', relayAck.hashes[0]);

  // Step 8: Wait for on-chain confirmation
  const status = await confirmationPromise;
  ws.close();

  if (status.status !== 'success') {
    throw new Error(`Swap failed on-chain: ${status.reason}`);
  }

  return { txHash: relayAck.hashes[0], status };
}

---

Edge Cases

tx-status TTL expiry

tx-status/{hash} subscriptions expire after 60 seconds. If a transaction takes longer — due to network congestion or cross-shard execution with many metachain rounds — the subscription expires without delivering an event.

When this happens:

1. Poll the MultiversX API: GET https://api.multiversx.com/transactions/{hash} until the status changes from pending.

2. Re-subscribe to tx-status/{hash} on the relayer immediately — the relayer may still receive the event if the block finalizes shortly after your subscription expired.

async function pollTransactionStatus(txHash, maxAttempts = 30, intervalMs = 2000) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`https://api.multiversx.com/transactions/${txHash}`);
    if (res.ok) {
      const tx = await res.json();
      if (tx.status !== 'pending') return tx;
    }
    await new Promise(r => setTimeout(r, intervalMs));
  }
  throw new Error('Transaction still pending after maximum polling attempts');
}

Cross-shard transactions

When the sender and the aggregator contract are on different shards, the transaction requires two block times: one on the sender's shard and one on the receiver's shard. The tx-status event fires after the receiver's shard processes the cross-shard message, not after the sender's block.

Expect cross-shard swaps to take roughly twice the block time of the slower shard. The networkStats stream exposes shard block times under blockTimeMsP50ByShard — see Gas Optimization for details.

Smart contract revert

If the actual swap output falls below amountOutMin — because price moved between quote and execution — the aggregator smart contract reverts. The transaction hash still appears on-chain with a fail status, and token balances are unchanged. Request a new quote and retry.

if (status.status === 'fail' && status.reason?.includes('execution failed')) {
  // Likely slippage exceeded — re-quote and retry
  const newQuote = await getQuote({ from, to, amountIn, slippage: 0.02 }); // widen slippage
  // ... retry flow
}

---

Related Pages

• Quickstart — Condensed end-to-end example

• Gas Optimization — Choosing the right gas price

• Quote Endpoint — Full parameter and response reference

• Transaction Relaying — Relay action reference

• Gas Statistics — gasStats message schema