Currency Conversion

Use the Conversion API to get a real-time preview of exchange rates, fees, and the final amount a user will receive before executing a swap or transfer. This is useful for displaying estimated outcomes to users before they confirm an action.

The conversion preview does not execute the conversion — it only calculates rates and fees at the current moment.

Using the SDK

Initialize


import { Pay100 } from "@100pay-hq/100pay.js";
 
const client = new Pay100({
  publicKey: "your_public_key",
  secretKey: "your_secret_key",
});

Preview a Conversion


const preview = await client.conversion.preview({
  amount: 500,
  from_symbol: "USDT",
  to_symbol: "BTC",
});
 
if ("convertedAmount" in preview) {
  // Simple result
  console.log(`You will receive: ${preview.convertedAmount} BTC`);
  console.log(`Fee: ${preview.feeInFromCurrency} USDT`);
  console.log(`Rate: 1 USDT = ${preview.toRate / preview.fromRate} BTC`);
} else {
  // Enhanced result — includes balance check, recommendations, etc.
  console.log("Can proceed:", preview.canProceed);
  console.log("Converted:", preview.conversion.convertedAmount);
}

Both from_symbol/to_symbol (snake_case) and fromSymbol/toSymbol (camelCase) are accepted — the SDK handles both for backward compatibility.

Parameters

Field	Type	Required	Description
`amount`	`number`	✅	Amount of the source currency to convert
`from_symbol`	`string`	✅	Source currency symbol (e.g. `"USDT"`, `"BTC"`)
`to_symbol`	`string`	✅	Target currency symbol (e.g. `"ETH"`, `"USDT"`)
`appId`	`string`	—	Your app ID (optional, for rate customization)
`mode`	`string`	—	Optional conversion mode flag

Response Types

The response is one of two shapes depending on the request context:

Simple Result — `CurrencyConversionResult`


{
  convertedAmount: 0.0092,             // Amount in target currency after fees
  totalAmount: 500,                    // Original input amount
  finalAmount: 0.0092,                 // Same as convertedAmount
  feeInUSD: 2.5,                       // Platform fee in USD
  feeInToCurrency: 0.000046,           // Fee in target currency
  feeInFromCurrency: 2.5,              // Fee in source currency
  conversionFeeInUSD: 1.25,            // Conversion-specific portion of the fee
  conversionFeeInToCurrency: 0.000023,
  conversionFeeInFromCurrency: 1.25,
  fromRate: 1,                         // USD rate of source currency
  toRate: 54347.82,                    // USD rate of target currency
  intermediateUSDAmount: 500,          // Mid-conversion USD value
  percentageConversionFee: 0.5,        // Fee as a percentage
}

Field	Description
`convertedAmount`	Final amount the user receives in the target currency
`totalAmount`	Input amount
`feeInUSD`	Total fee in USD
`feeInFromCurrency`	Total fee in the source currency
`fromRate` / `toRate`	USD exchange rates — divide `toRate / fromRate` for direct rate
`percentageConversionFee`	Fee percentage charged

Enhanced Result — `EnhancedConversionResponse`

Returned when the API has additional context (balance, adjustments, recommendations). Check "convertedAmount" in preview to distinguish:


{
  conversion: CurrencyConversionResult,     // Same as simple result above
  canProceed: true,                          // Whether conversion can proceed
  adjustedConversion: {
    wasAdjusted: false,
    adjustedAmount: 500,
    adjustedConvertedAmount: 0.0092,
    reasonForAdjustment: "",
    // ...
  },
  maximumConversion: {
    maxConvertibleAmount: 1000,
    maxConvertedAmount: 0.0184,
    remainingBalance: 500,
    canConvertEntireBalance: true,
    // ...
  },
  balance: {
    currentBalance: 1000,
    availableBalance: 1000,
    hasSufficientBalance: true,
    shortfall: 0,
    balanceAfterConversion: 500,
  },
  recommendations: {
    useAdjustedAmount: false,
    convertEntireBalance: false,
    suggestedAmount: 500,
    maxPossibleAmount: 1000,
  },
  wallets: {
    fromWallet: { exists: true, symbol: "USDT", walletType: "crypto" },
    toWallet: { exists: true, symbol: "BTC", walletType: "crypto" },
  },
  restrictions: {
    isWhitelisted: true,
    validationPassed: true,
    additionalValidations: {},
  },
  user: { status: "active", canTransact: true },
  mode: "live",
  timestamp: "2026-03-03T22:00:00Z",
}

Handling Both Response Types


const preview = await client.conversion.preview({
  amount: 100,
  from_symbol: "USDT",
  to_symbol: "ETH",
});
 
if ("convertedAmount" in preview) {
  // Simple result
  const { convertedAmount, feeInUSD, fromRate, toRate } = preview;
  const rate = toRate / fromRate;
 
  displayToUser({
    youSend: `100 USDT`,
    youReceive: `${convertedAmount} ETH`,
    rate: `1 USDT = ${rate} ETH`,
    fee: `${feeInUSD} USD`,
  });
} else {
  // Enhanced result
  if (!preview.canProceed) {
    alert("Conversion cannot proceed: insufficient balance or restriction.");
    return;
  }
 
  if (preview.adjustedConversion.wasAdjusted) {
    // Notify user that the amount was adjusted
    console.log(`Amount adjusted: ${preview.adjustedConversion.reasonForAdjustment}`);
  }
 
  const { convertedAmount } = preview.conversion;
  displayToUser({ youReceive: `${convertedAmount} ETH` });
}

TypeScript Types


type CurrencyConversionPayload = {
  amount: number;
  from_symbol?: string;
  to_symbol?: string;
  fromSymbol?: string; // alias for backward compat
  toSymbol?: string;   // alias for backward compat
  appId?: string;
  mode?: string;
};
 
type CurrencyConversionResult = {
  convertedAmount: number;
  totalAmount: number;
  finalAmount: number;
  feeInUSD: number;
  feeInToCurrency: number;
  feeInFromCurrency: number;
  conversionFeeInUSD: number;
  conversionFeeInToCurrency: number;
  conversionFeeInFromCurrency: number;
  fromRate: number;
  toRate: number;
  intermediateUSDAmount: number;
  percentageConversionFee: number;
};

Next Steps

Asset Transfers — execute actual transfers after previewing rates
Subaccounts — manage per-customer wallet balances