Configuration

The SDK provides three client classes, each with its own configuration.

SteelSwapClient (v1 API)

import { SteelSwapClient } from '@steelswap/steelswap-sdk'

const client = new SteelSwapClient({
  baseUrl: 'https://api.steelswap.io', // API base URL (default)
  timeout: 30000, // Request timeout in ms
  token: 'd82983fe50d8eae...', // Authentication token
  partner: 'examplepartner', // Partner identifier
  numericFormat: 'string', // Output format for numbers
  fetch: customFetch, // Custom fetch implementation
})

token

• Type: string
• Default: undefined

Authentication token sent as the token header on all API requests.

partner

• Type: string
• Default: undefined

Partner identifier automatically injected into swap requests (estimateSwap, buildSwap, cancelSwap). Contact SteelSwap to obtain your partner code.

const client = new SteelSwapClient({
  partner: 'examplepartner',
})

// Partner is automatically included in swap requests
await client.estimateSwap({
  tokenA: 'lovelace',
  tokenB: 'policy.asset',
  quantity: '10000000',
})

numericFormat

• Type: 'string' | 'number' | 'bigint' | 'Big'
• Default: 'string'

Controls the format of numeric values in API responses. The client is generic and TypeScript will infer the correct return types based on your choice.

// Default: strings (safest for large numbers)
const stringClient = new SteelSwapClient({ numericFormat: 'string' })
const estimate1 = await stringClient.estimateSwap({ ... })
estimate1.quantityB // type: string

// JavaScript numbers (convenient but may lose precision for large values)
const numberClient = new SteelSwapClient({ numericFormat: 'number' })
const estimate2 = await numberClient.estimateSwap({ ... })
estimate2.quantityB // type: number

// BigInt (for integer precision)
const bigintClient = new SteelSwapClient({ numericFormat: 'bigint' })
const estimate3 = await bigintClient.estimateSwap({ ... })
estimate3.quantityB // type: bigint

// Big.js instances (for decimal precision and calculations)
const bigClient = new SteelSwapClient({ numericFormat: 'Big' })
const estimate4 = await bigClient.estimateSwap({ ... })
estimate4.quantityB // type: Big
estimate4.quantityB.times('0.997') // Big.js methods available

baseUrl

• Type: string
• Default: 'https://api.steelswap.io'

The base URL for the SteelSwap API.

Environment	URL
Production	https://api.steelswap.io
Development	https://apidev.steelswap.io

timeout

• Type: number
• Default: 30000

Request timeout in milliseconds. Requests that take longer will be aborted.

fetch

• Type: typeof fetch
• Default: Global fetch

Custom fetch implementation. Useful for request/response logging or using a different HTTP client.

SteelSwapV2Client (v2 API)

import { SteelSwapV2Client } from '@steelswap/steelswap-sdk'

const v2Client = new SteelSwapV2Client({
  baseUrl: 'https://cicdapi.steelswap.io', // v2 API base URL (default)
  timeout: 30000, // Request timeout in ms
  bearerToken: 'your-v2-bearer-token', // Required
  fetch: customFetch, // Custom fetch implementation
})

bearerToken

• Type: string
• Required

Bearer token sent as Authorization: Bearer <token> on all requests. This is different from the v1 API which uses a custom token header.

baseUrl

• Type: string
• Default: 'https://cicdapi.steelswap.io'

timeout

• Type: number
• Default: 30000

fetch

• Type: typeof fetch
• Default: Global fetch

C3PriceClient (C3 Price API)

import { C3PriceClient } from '@steelswap/steelswap-sdk'

const priceClient = new C3PriceClient({
  baseUrl: 'https://cicdapi.steelswap.io', // C3 API base URL (default)
  timeout: 30000, // Request timeout in ms
  bearerToken: 'your-c3-bearer-token', // Required for price endpoints
  fetch: customFetch, // Custom fetch implementation
})

bearerToken

• Type: string
• Required

Bearer token for authenticated endpoints. Note that getGroups() and healthCheck() do not require authentication and will skip the Authorization header.

baseUrl

• Type: string
• Default: 'https://cicdapi.steelswap.io'

timeout

• Type: number
• Default: 30000

fetch

• Type: typeof fetch
• Default: Global fetch

Working with Numbers

Input

All numeric values (quantities, slippage, etc.) can be passed as:

• Numbers: 10000000
• Strings: '10000000'
• BigInt: 10000000n
• Big.js instances: new Big('10000000')

import Big from 'big.js'

// All of these work regardless of numericFormat
await client.estimateSwap({
  tokenA: 'lovelace',
  tokenB: 'policy.asset',
  quantity: '10000000', // string
})

await client.estimateSwap({
  tokenA: 'lovelace',
  tokenB: 'policy.asset',
  quantity: 10000000n, // bigint
})

const amount = new Big('10000000')
await client.estimateSwap({
  tokenA: 'lovelace',
  tokenB: 'policy.asset',
  quantity: amount, // Big instance
})

Output

Output format is controlled by numericFormat (v1 client only). The v2 and C3 clients always return plain number values.

Format	Type	Best For
'string'	string	Default, safe for any size, easy serialization
'number'	number	Simple math, small values (< 2^53)
'bigint'	bigint	Large integers, native JS support
'Big'	Big	Decimal precision, complex calculations

// Example with Big.js for calculations
const client = new SteelSwapClient({ numericFormat: 'Big' })
const estimate = await client.estimateSwap({ ... })

// Direct calculations on response values
const withSlippage = estimate.quantityB.times('0.99')
const formatted = estimate.quantityB.div(1_000_000).toFixed(2) // "50.00" ADA

Custom Fetch Example

const customFetch: typeof fetch = async (url, options) => {
  console.log('Request:', url)

  const response = await fetch(url, {
    ...options,
    headers: {
      ...options?.headers,
      'X-Custom-Header': 'value',
    },
  })

  console.log('Response:', response.status)
  return response
}

// Works with all three clients
const client = new SteelSwapClient({ fetch: customFetch })
const v2Client = new SteelSwapV2Client({ bearerToken: '...', fetch: customFetch })
const priceClient = new C3PriceClient({ bearerToken: '...', fetch: customFetch })

Environment-Specific Setup

Node.js

The SDK works out of the box in Node.js 18+ which includes native fetch.

For older Node.js versions, use a fetch polyfill:

import fetch from 'node-fetch'

const client = new SteelSwapClient({
  fetch: fetch as unknown as typeof globalThis.fetch,
})

Browser

No additional setup required. The SDK uses the native fetch API.

React Native

// React Native has built-in fetch support
const client = new SteelSwapClient()