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
a wallet that has accepted the current Terms of Use
an ss_... API token stored outside source control
exact-integer handling for token amounts and field identifiers

Pool and token discovery, pool analytics, and Explore market reads are public. Route requests need 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 fields, and scale values. The fee_percent field records the creation fee. Use current_fee_percent for the live fee before Pricing Terms reductions, when available. Both fields use basis points.

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 /explore/transactions for the public market transaction feed

These endpoints are public. Call getJson with { publicEndpoint: true } for each one. Use GET /pools/{key}/oracle for an indexed oracle snapshot. See Pool oracle for supported windows and unavailable-data states. Use offset pagination for Explore token and pool lists. Use the returned nextCursor for Explore transactions. See Pagination and errors. When the API encodes an integer 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`	For `terms_required`, repeat wallet sign-in; otherwise check permissions
`404` from `/route`	Treat the route as unavailable
`429`	Wait before retrying
transient `5xx`	Retry within the bounded policy

The bot can request a short-lived WebSocket ticket with its API token or a browser wallet session. Follow the WebSocket feed. After any disconnect, reload REST state before acting on new events.

Transaction boundary

The API supplies indexed data and routes. Authenticated clients can read GET /pools/{key}/initialized-ticks when constructing transactions. Each tick includes its exact mapping_key; preserve that value for mapping reads and transaction inputs. Do not use the tick number as its mapping key. 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 Swap when the bot must submit trades.

Start

Trade

Provide liquidity

Integration guides

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