Skip to main content
Step-by-step guide to creating a currency conversion in PIK using either the Rates or Quotes method.”
Use this guide to create your first FX conversion in PIK. You can convert any supported currency pair held in your PIK wallet — either your platform wallet balance or a connected account wallet balance.

​
Before you start

Make sure you have:
  • A PIK API key with FX conversion permissions.
  • A wallet balance in the currency you want to sell. Check your balance via GET /api/v1/accounts//wallet/balances before converting.
  • The FX capability activated on the account. For connected accounts, fx_conversion must be in the list of activated capabilities.

​
Option A — Convert using Rates (immediate, live rate)

This is the simplest path. One API call converts immediately at the live market rate. Call POST /api/v1/fx/conversions with the following fields: sell_currency — The currency you are converting from. For example USDT. buy_currency — The currency you are converting to. For example AUD. sell_amount — The amount of sell_currency you want to convert. For example 500.00. Alternatively provide buy_amount if you want to specify how much of the target currency you want to receive and let PIK calculate the sell side. conversion_type — Set this to rate. reference — An optional string for your own records to identify this conversion. Include the x-on-behalf-of header if converting on behalf of a connected account. PIK will respond with a conversion object including the conversion_id, the rate applied, the sell amount debited, the buy amount credited, and the status. A status of converted means the conversion completed successfully and the buy currency has been credited to the wallet.

​
Option B — Convert using Quotes (locked rate)

Use this path when you need a guaranteed rate before committing. Step 1 — Request a quote. Call POST /api/v1/fx/quotes with sell_currency, buy_currency, and either sell_amount or buy_amount. PIK returns a quote object with a guaranteed rate, a quote_id, and a quote_expiry timestamp. Step 2 — Execute the conversion. Before the quote_expiry time passes, call POST /api/v1/fx/conversions with conversion_type set to quote and the quote_id from step 1. PIK executes at the locked rate.

​
Checking conversion status

Call GET /api/v1/fx/conversions/conversion_id to retrieve the status of a conversion. Conversion statuses:
  • pending — Conversion submitted, processing in progress.
  • converted — Conversion completed. Buy currency credited to wallet.
  • failed — Conversion could not be completed. Check the failure_reason field.

​
Common errors

Insufficient balance — The sell currency balance is lower than the sell amount requested. Check your wallet balance before converting. Below minimum amount — The requested conversion amount is below the minimum for that currency pair. Increase the amount or check the minimum thresholds in your PIK merchant agreement. Quote expired — The quote_id used has passed its expiry time. Request a new quote and resubmit immediately. Capability not activated — The fx_conversion capability has not been activated on the account. Activate it via the capabilities endpoint before attempting a conversion.