Build a market-data bot

This guide covers data collection and route lookup. It does not cover record selection, proving, transaction submission, or claims.

Before you start

You need:

Node.js with built-in fetch
an invited wallet
an ss_... API token stored outside source control
exact-integer handling for token amounts and field identifiers

Pool and token discovery are public. Routes, history, positions, swaps, balances, and detailed market reads require the API token.

1. Create an API client

const baseUrl = "https://api.swap.shield.fi";
const apiToken = process.env.SHIELD_SWAP_API_TOKEN;

if (!apiToken) {
  throw new Error("Set SHIELD_SWAP_API_TOKEN before starting the bot");
}

async function getJson(path, { publicEndpoint = false } = {}) {
  const response = await fetch(`${baseUrl}${path}`, {
    headers: publicEndpoint
      ? {}
      : { Authorization: `Bearer ${apiToken}` },
  });

  if (!response.ok) {
    throw new Error(`${path} returned ${response.status}`);
  }

  return response.json();
}

Create the token through the wallet-session flow in Authentication.

2. Discover tokens and pools

const [{ data: tokens }, { data: pools }] = await Promise.all([
  getJson("/tokens", { publicEndpoint: true }),
  getJson("/pools?limit=100&offset=0", { publicEndpoint: true }),
]);

Continue requesting pool pages until data is empty or pagination shows that all rows have been returned. Keep the exact pool key, token IDs, fee, and scale values.

3. Load the data your strategy uses

Do not fetch every endpoint for every pool. Request only the resources needed by the strategy:

GET /pools/{key} for public pool metadata
GET /pools/{key}/stats for current indexed statistics
GET /pools/{key}/trades for trade history
GET /pools/{key}/ohlcv for candles
GET /swaps for indexed swap history

When the API encodes an amount as a JSON string, parse it with an arbitrary-precision integer type. Never pass it through JavaScript number.

4. Request a route

const query = new URLSearchParams({
  token_in: inputToken,
  token_out: outputToken,
  amount_in: "1000000",
});

const route = await getJson(`/route?${query}`);

The router returns at most three hops. A route is current indexed guidance, not an execution guarantee. Before submission, apply the transaction’s price limit, minimum output, deadline, record checks, and final-state reconciliation.

5. Refresh state safely

Use request timeouts, bounded exponential backoff, jitter, and a maximum retry count.

Response	Bot action
`401`	Replace or reissue the API token
`403`	Stop; the wallet does not have the required access
`404` from `/route`	Treat the route as unavailable
`429`	Wait before retrying
transient `5xx`	Retry within the bounded policy

If the bot uses a browser wallet session, it can request a short-lived WebSocket ticket and follow the WebSocket feed. After any disconnect, reload REST state before acting on new events.

Transaction boundary

The API supplies indexed data, routes, and current input schemas. Your wallet or proving client still owns:

token-record selection and reservation
transaction construction and signing
proof generation and submission
swap-output claim handling
accepted, rejected, and unknown transaction states
final public-state and record reconciliation

Continue with Transaction execution when the bot must submit trades.

Start

Build

Trade

Provide liquidity

Build a market-data bot

Before you start

1. Create an API client

2. Discover tokens and pools

3. Load the data your strategy uses

4. Request a route

5. Refresh state safely

Transaction boundary

​Before you start

​1. Create an API client

​2. Discover tokens and pools

​3. Load the data your strategy uses

​4. Request a route

​5. Refresh state safely

​Transaction boundary

Before you start

1. Create an API client

2. Discover tokens and pools

3. Load the data your strategy uses

4. Request a route

5. Refresh state safely

Transaction boundary