SwapClient

Overview

The SwapClient provides access to exchange rate discovery and swapping functionality for the Bloque platform. It serves as the main entry point for:

Finding available exchange rates between asset pairs
Accessing PSE payment utilities
Managing generic bank transfer cash-outs to Colombian banks

Constructor

The SwapClient is automatically initialized when you create a Bloque SDK instance. Access it via bloque.swap.

import { Bloque } from '@bloque/sdk';

const bloque = new Bloque({ apiKey: 'your-api-key' });
const swapClient = bloque.swap;

Properties

pse

PseClient

required

PSE (Pagos Seguros en Línea) utilities client for listing banks and creating PSE swap orders.See PseClient for details.

bankTransfer

BankTransferClient

required

Generic bank transfer client for cash-out swaps supporting all Colombian banks.See BankTransferClient for details.

Methods

findRates()

Retrieves available exchange rates for a given asset pair with optional filters.

async findRates(params: FindRatesParams): Promise<FindRatesResult>

Parameters

params

FindRatesParams

required

Rate search parameters

Show FindRatesParams properties

fromAsset

string

required

Source asset with precision (e.g., "COP/2" where /2 indicates 2 decimal places)Example: "COP/2"

toAsset

string

required

Destination asset with precision (e.g., "DUSD/6" where /6 indicates 6 decimal places)Example: "DUSD/6"

fromMediums

string[]

required

Source payment mediums (e.g., PSE, Bancolombia, Nequi)Example: ["bancolombia", "pse"]

toMediums

string[]

required

Destination payment mediums (e.g., Pomelo, Kusama)Example: ["kusama", "pomelo"]

amountSrc

string

Source amount as bigint string (scaled by asset precision). Provide this OR amountDst, not both.Example: "1000000" represents 10000.00 for COP/2

amountDst

string

Destination amount as bigint string (scaled by asset precision). Provide this OR amountSrc, not both.Example: "50000" represents 0.5000 for USD/4

sort

'asc' | 'desc'

default:"asc"

Sort order: 'asc' (best rate first) or 'desc' (highest rate first)

sortBy

'rate' | 'at'

default:"rate"

Sort by field: 'rate' (by exchange ratio) or 'at' (by calculation time)

Returns

FindRatesResult

object

Show FindRatesResult properties

rates

SwapRate[]

Array of available exchange rates

Show SwapRate properties

string

Unique rate identifier

sig

string

Rate signature (use this when creating orders)

swapSig

string

Swap signature

maker

string

Maker identifier

edge

[string, string]

Asset edge tuple: [fromAsset, toAsset]

fee

Fee

Fee details for this rate

Show Fee properties

number

Timestamp when the fee was calculated

value

number

Total fee value

formula

string

Formula used to calculate the fee

components

FeeComponent[]

Individual fee components

Show FeeComponent properties

number

Timestamp when this component was calculated

name

string

Component name (e.g., 'take_rate', 'exchange_rate', 'pse_fee')

type

'percentage' | 'rate' | 'fixed'

Type of fee component

value

number | string

Component value

percentage

number

Percentage value (only for percentage type)

pair

string

Currency pair (only for rate type)

amount

number

Fixed amount (only for fixed type)

string

Timestamp when the rate was created

until

string

Timestamp until the rate is valid

fromMediums

string[]

Available source mediums

toMediums

string[]

Available destination mediums

rate

[number, number]

Rate tuple: [sourceAmount, destinationAmount]

ratio

number

Exchange ratio (destination amount per source amount)

fromLimits

[string, string]

Source amount limits: [min, max]

toLimits

[string, string]

Destination amount limits: [min, max]

createdAt

string

Creation timestamp

updatedAt

string

Last update timestamp

Example

const result = await bloque.swap.findRates({
  fromAsset: 'COP/2',
  toAsset: 'DUSD/6',
  fromMediums: ['bancolombia'],
  toMediums: ['kusama'],
  amountSrc: '50000000' // 500000.00 COP (scaled by 2 decimals)
});

console.log('Exchange ratio:', result.rates[0].ratio);
console.log('Fee breakdown:', result.rates[0].fee.components);

Fee Structure

Exchange rates include detailed fee information with multiple components:

Fee Component Types

percentage

FeeComponentType

Percentage-based fee (e.g., 2.5% of transaction)

percentage: The percentage value (e.g., 2.5)
Used for: Platform fees, take rates

rate

FeeComponentType

Exchange rate-based fee

pair: Currency pair (e.g., “USD/COP”)
Used for: Exchange rate spreads

fixed

FeeComponentType

Fixed amount fee

amount: Fixed fee amount
Used for: PSE transaction fees, bank transfer fees

Fee Calculation Example

const rate = result.rates[0];

console.log('Total fee:', rate.fee.value);
console.log('Fee formula:', rate.fee.formula);

// Inspect individual components
for (const component of rate.fee.components) {
  console.log(`${component.name} (${component.type}):`, component.value);
  
  if (component.type === 'percentage') {
    console.log('  Percentage:', component.percentage);
  } else if (component.type === 'rate') {
    console.log('  Pair:', component.pair);
  } else if (component.type === 'fixed') {
    console.log('  Amount:', component.amount);
  }
}

Rate Calculation

Rates are calculated based on:

Base exchange rate: The market rate between the two assets
Medium fees: Fees charged by payment providers (e.g., PSE, bank transfers)
Platform fees: Bloque’s service fee
Amount: The source or destination amount you specify

Understanding the Rate Tuple

The rate field is a tuple [sourceAmount, destinationAmount] representing the conversion:

const [srcAmount, dstAmount] = rate.rate;
const ratio = rate.ratio; // dstAmount / srcAmount

// Example: [100000, 95000] means 1000.00 COP = 950.00 COP after fees
// Ratio: 0.95 (95% conversion after 5% fees)

Amount Limits

Each rate includes minimum and maximum amounts:

const [minSrc, maxSrc] = rate.fromLimits;
const [minDst, maxDst] = rate.toLimits;

console.log(`Source range: ${minSrc} - ${maxSrc}`);
console.log(`Destination range: ${minDst} - ${maxDst}`);

FindRatesParams - Parameters for rate search
FindRatesResult - Result containing available rates
SwapRate - Individual exchange rate details
Fee - Fee structure and breakdown
FeeComponent - Individual fee component

SDK

Accounts

Swap

Identity

Compliance

Organizations

Core

Overview

Constructor

Properties

pse

bankTransfer

Methods

findRates()

Parameters

Returns

Example

Fee Structure

Fee Component Types

Fee Calculation Example

Rate Calculation

Understanding the Rate Tuple

Amount Limits

Build docs developers (and LLMs) love

SDK

Accounts

Swap

Identity

Compliance

Organizations

Core

​Overview

​Constructor

​Properties

​pse

​bankTransfer

​Methods

​findRates()

​Parameters

​Returns

​Example

​Fee Structure

​Fee Component Types

​Fee Calculation Example

​Rate Calculation

​Understanding the Rate Tuple

​Amount Limits

​Related Types

Build docs developers (and LLMs) love

Overview

Constructor

Properties

pse

bankTransfer

Methods

findRates()

Parameters

Returns

Example

Fee Structure

Fee Component Types

Fee Calculation Example

Rate Calculation

Understanding the Rate Tuple

Amount Limits

Related Types