Skip to main content

Radom Conversion API guide

Radom's Conversion API lets you request quotes and accept conversions between supported assets and networks.

This guide is aligned to the public API reference currently included in the docs repository. The documented flow is:

  1. List supported conversion pairs so your UI only offers valid routes.
  2. Request a quote for a source asset, destination asset, and amount.
  3. Accept the quote to initiate the conversion.

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​

FunctionMethodEndpointResponse highlight
List supported pairsGET/conversion/pairs[{from, into, min_from_amount}]
Request a quotePOST/conversion/quote{quoteId, quotedAmount}
Accept a quotePOST/conversion/accept{success}

1. List supported conversion pairs​

When to use: On startup, when rendering a conversion picker, or whenever you need to validate a user's requested route.
What you get: A list of source/destination payment method pairs plus the minimum supported source amount.

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

Example response:

[
  {
    "from": { "network": "Bitcoin", "token": null },
    "into": {
      "network": "Ethereum",
      "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    },
    "min_from_amount": "0.001"
  },
  {
    "from": { "network": "Ethereum", "token": null },
    "into": {
      "network": "Ethereum",
      "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    },
    "min_from_amount": "0.01"
  }
]

Use this response to power currency pickers, pre-fill selections, and block unsupported combinations before the user requests a quote.

2. Request a quote​

When to use: Before the user commits to a conversion.
What you send: fromAmount plus from and into payment method objects.
What you get: A quoteId plus the quoted destination amount.

curl -X POST "https://api.radom.com/conversion/quote" \
  -H "Authorization: RADOM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAmount": "0.05",
    "from": { "network": "Bitcoin", "token": null },
    "into": {
      "network": "Ethereum",
      "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    }
  }'

Typical response:

{
  "quoteId": "b2f2f0e1-1af5-44e4-8b04-3d0e0aa8b8b0",
  "quotedAmount": "3050.12"
}

Store the quoteId together with the user's selected route and source amount so you can accept the same quote immediately after confirmation.

3. Accept the quote (execute)​

When to use: Immediately after the user confirms they want to proceed.
What you send: The quoteId returned by the quote endpoint.
What you get: A success flag indicating whether the quote was accepted and the conversion was initiated.

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"
  }'

Example response:

{
  "success": true
}

Treat a successful response as confirmation that Radom accepted the quote and initiated the conversion request.

Payment method object format​

Conversion endpoints use Radom payment method objects:

{
  "network": "Ethereum",
  "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}

For native assets such as BTC or ETH, token is null. For tokenized assets, token is the token address or symbol documented for that network.

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 quoteAndAcceptConversion(fromAmount) {
  const from = { network: "Bitcoin", token: null };
  const into = {
    network: "Ethereum",
    token: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  };

  // 1) list pairs (optional, but recommended when building a picker)
  const pairs = (await axios.get(`${RADOM_API}/conversion/pairs`, { headers })).data;
  const isSupported = pairs.some(
    (pair) =>
      pair.from.network === from.network &&
      pair.from.token === from.token &&
      pair.into.network === into.network &&
      pair.into.token === into.token
  );

  if (!isSupported) {
    throw new Error("Unsupported conversion pair");
  }

  // 2) quote
  const quote = (await axios.post(
    `${RADOM_API}/conversion/quote`,
    {
      fromAmount: String(fromAmount),
      from,
      into
    },
    { headers }
  )).data;

  // 3) accept
  return (await axios.post(
    `${RADOM_API}/conversion/accept`,
    {
      quoteId: quote.quoteId
    },
    { headers }
  )).data;
}

Error handling & best practices​

  • Validate pairs before quoting: Use GET /conversion/pairs so your UI only exposes routes that are currently supported.
  • Respect minimum amounts: Check min_from_amount before allowing the user to request a quote.
  • Persist the quote context: Store the selected from, into, fromAmount, and returned quoteId together so you can accept the intended quote cleanly.
  • Refresh your route list regularly: Supported pairs can change over time, so fetch them again on startup or when opening your conversion flow.
  • Keep tokens secure: Store API tokens safely and rotate them periodically.

Quick reference​

FunctionMethodEndpointResponse
List pairsGET/conversion/pairs[{from, into, min_from_amount}]
QuotePOST/conversion/quote{quoteId, quotedAmount}
AcceptPOST/conversion/accept{success}

See also​