Radom Conversion API guide

Radom's Conversion API lets you move value between supported assets and networks (for example BTC → USDC on Ethereum) with the proceeds settling directly into your Radom balance. A typical workflow is:

1. List conversion pairs to understand which routes your integration can offer.
2. Request a quote for the specific source/destination pair and amount.
3. Accept the quote so Radom executes the conversion on your behalf.
4. Handle webhook notifications (or poll) to reconcile the final status.

Use the sections below as a blueprint for integrating these steps into your application.

Creating an API token

Create a Developer API token in the Radom Dashboard and store it securely. Every endpoint shown in this guide expects the token in the Authorization header along with a JSON payload when applicable:

Authorization: RADOM_API_TOKEN
Content-Type: application/json

Endpoints overview

Function	Method	Endpoint	Response highlight
List supported pairs	GET	/conversion/pairs	{source, destination} combinations
Request a quote	POST	/conversion/quote	{quoteId, price, fees, expiresAt}
Accept a quote	POST	/conversion/accept	{conversionId, status, destinationAmount}

1. List supported conversion pairs

When to use: On startup, when rendering a currency picker, or whenever you need to validate a user's requested route.
What you get: A list of {source, destination} assets/networks you can convert between.

curl -X GET "https://api.radom.com/conversion/pairs" \
  -H "Authorization: RADOM_API_TOKEN"

Example response:

{
  "pairs": [
    {
      "source": { "network": "Bitcoin", "token": null },
      "destination": { "network": "Ethereum", "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }
    },
    {
      "source": { "network": "Ethereum", "token": null },
      "destination": { "network": "Ethereum", "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }
    }
  ]
}

Use this data to power autocomplete lists, pre-fill selections, and block unsupported combinations before quoting.

2. Request a quote

When to use: Before the user commits to a conversion.
What you send: Source/destination objects plus the amount to convert.
What you get: The executable quoteId, price, fee breakdown, and an expiresAt timestamp.

curl -X POST "https://api.radom.com/conversion/quote" \
  -H "Authorization: RADOM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "network": "Bitcoin", "token": null },
    "destination": { "network": "Ethereum", "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" },
    "amount": "0.05",
    "slippageBps": 50,
    "memo": "Order #12345"
  }'

Typical response:

{
  "quoteId": "b2f2f0e1-1af5-44e4-8b04-3d0e0aa8b8b0",
  "price": "61000.25",
  "sourceAmount": "0.05",
  "destinationAmount": "3050.12",
  "fee": { "total": "7.50", "currency": "USDC" },
  "expiresAt": "2025-10-23T12:59:30Z"
}

Never cache quotes past expiresAt. If the user hesitates or the deadline passes, request a new quote so the pricing stays valid.

3. Accept the quote (execute)

When to use: Immediately after the user confirms they want to proceed.
What you send: The quoteId returned above (optionally add a clientReferenceId to link the conversion to your order).
What you get: The conversionId, its status, and resulting amount details.

curl -X POST "https://api.radom.com/conversion/accept" \
  -H "Authorization: RADOM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "b2f2f0e1-1af5-44e4-8b04-3d0e0aa8b8b0",
    "clientReferenceId": "order-12345"
  }'

Example response:

{
  "conversionId": "c9a2d7d6-7a6b-4d27-9b7f-47fdf7b8f3b2",
  "status": "Pending",
  "destinationAmount": "3050.12",
  "destination": { "network": "Ethereum", "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }
}

Treat Pending as in-flight. Use the conversionId to reconcile downstream, and rely on webhooks or status polling to know when the conversion is final.

4. Receiving webhook notifications

Configure your webhook endpoint in the Dashboard and verify signatures as you would for other Radom events. A completed conversion triggers a conversion.completed event:

{
  "eventType": "conversion.completed",
  "eventData": {
    "conversion": {
      "conversionId": "c9a2d7d6-7a6b-4d27-9b7f-47fdf7b8f3b2",
      "status": "Completed",
      "source": { "network": "Bitcoin", "token": null, "amount": "0.05" },
      "destination": {
        "network": "Ethereum",
        "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "amount": "3050.12"
      }
    }
  },
  "radomData": {
    "organizationId": "…"
  }
}

Store the conversionId alongside your internal IDs so you can reconcile each webhook back to the original quote/order pair. Polling is possible, but webhooks are recommended for the most reliable experience.

Putting it together (Node.js example)

import axios from "axios";

const RADOM_API = "https://api.radom.com";
const HEADERS = {
  Authorization: process.env.RADOM_API_TOKEN,
  "Content-Type": "application/json"
};

export async function convertBtcToUsdc(sourceAmount, clientRef = undefined) {
  // 1) list pairs (optional)
  // const pairs = (await axios.get(`${RADOM_API}/conversion/pairs`, { headers: HEADERS })).data;

  // 2) quote
  const quote = (await axios.post(
    `${RADOM_API}/conversion/quote`,
    {
      source: { network: "Bitcoin", token: null },
      destination: { network: "Ethereum", token: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" },
      amount: String(sourceAmount),
      slippageBps: 50,
      memo: clientRef
    },
    { headers: HEADERS }
  )).data;

  // 3) accept
  const accept = (await axios.post(
    `${RADOM_API}/conversion/accept`,
    {
      quoteId: quote.quoteId,
      clientReferenceId: clientRef
    },
    { headers: HEADERS }
  )).data;

  return accept; // { conversionId, status, ... }
}

Error handling & best practices

• Quotes expire: Always compare the current time to expiresAt. If a quote is stale, fetch a new one before proceeding.
• Validate pairs: Regularly call GET /conversion/pairs so your UI only exposes supported routes.
• Idempotency: If Radom exposes an idempotency header, include it when retrying quote or accept requests to avoid duplicate conversions.
• Slippage protection: Use the slippageBps field to bound price movement tolerance.
• Logging: Persist quoteId, conversionId, and any clientReferenceId or webhook eventId so you can trace every conversion end-to-end.
• Security: Keep API tokens secret, rotate them periodically, and verify webhook signatures before trusting payloads.

FAQ

• Where do converted funds settle? Into your Radom balance in the destination asset, viewable in the Dashboard.
• Can I convert by output amount? If the API reference lists support for "convert by destination amount" or similar modes, pass the relevant field in the quote request.
• Do I have to use webhooks? Webhooks are strongly recommended, but polling a status endpoint is possible if your architecture demands it.

Quick reference

Function	Method	Endpoint	Response
List pairs	GET	/conversion/pairs	{source, destination}
Quote	POST	/conversion/quote	{quoteId, price, fees, expiresAt}
Accept	POST	/conversion/accept	{conversionId, status}

Need examples for additional chains or tokens (for instance Ethereum USDT, Solana USDC, or Tron USDT)? Let us know so we can include multi-chain token formats and contract addresses in this guide.