Fiat On-Ramp

Hypermid integrates with RampNow to provide a fiat-to-crypto on-ramp. Users can purchase crypto using credit cards, debit cards, and bank transfers, and receive tokens directly on their preferred blockchain.

Flow Overview

Get Configuration

Fetch supported fiat currencies and payment methods via GET /v1/onramp/config.

Get Available Assets

Fetch purchasable crypto assets via GET /v1/onramp/assets.

Get a Quote

Get pricing for the fiat-to-crypto conversion via POST /v1/onramp/quote.

Create Checkout

Create a checkout session and get a redirect URL via POST /v1/onramp/checkout.

Redirect User

Send the user to the checkout URL to complete payment.

Track Status

Poll the order status via GET /v1/onramp/status until completion.

Step 1: Get Configuration

Fetch the available fiat currencies and payment methods:

const config = await client.getOnrampConfig();

console.log("Supported currencies:", config.currencies);
// ["USD", "EUR", "GBP", ...]

console.log("Payment methods:", config.paymentMethods);
// ["credit_card", "debit_card", "bank_transfer", ...]

curl https://api.hypermid.io/v1/onramp/config \
  -H "X-API-Key: your-api-key"

Step 2: Get Available Assets

Fetch the list of crypto assets available for purchase:

const assets = await client.getOnrampAssets();

for (const asset of assets.assets) {
  console.log(`${asset.symbol} on chain ${asset.chainId}: min ${asset.minAmount}, max ${asset.maxAmount}`);
}

curl https://api.hypermid.io/v1/onramp/assets \
  -H "X-API-Key: your-api-key"

Step 3: Get a Quote

Request a quote for the fiat-to-crypto conversion:

const quote = await client.getOnrampQuote({
  fiatCurrency: "USD",
  cryptoAsset: "ETH",
  chainId: 1,
  fiatAmount: 100,            // $100 USD
  paymentMethod: "credit_card",
  walletAddress: "0xYourWalletAddress",
});

console.log("You'll receive:", quote.cryptoAmount, "ETH");
console.log("Exchange rate:", quote.exchangeRate);
console.log("Fees:", quote.fees);
console.log("Total charge:", quote.totalFiatAmount, quote.fiatCurrency);

curl -X POST "https://api.hypermid.io/v1/onramp/quote" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "fiatCurrency": "USD",
    "cryptoAsset": "ETH",
    "chainId": 1,
    "fiatAmount": 100,
    "paymentMethod": "credit_card",
    "walletAddress": "0xYourWalletAddress"
  }'

Step 4: Create Checkout Session

Create a checkout session to get a payment URL:

const checkout = await client.createOnrampCheckout({
  fiatCurrency: "USD",
  cryptoAsset: "ETH",
  chainId: 1,
  fiatAmount: 100,
  paymentMethod: "credit_card",
  walletAddress: "0xYourWalletAddress",
  redirectUrl: "https://yourapp.com/onramp/callback",
});

console.log("Checkout URL:", checkout.checkoutUrl);
console.log("Order UID:", checkout.orderUid);

// Redirect user to the checkout URL
window.location.href = checkout.checkoutUrl;

curl -X POST "https://api.hypermid.io/v1/onramp/checkout" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "fiatCurrency": "USD",
    "cryptoAsset": "ETH",
    "chainId": 1,
    "fiatAmount": 100,
    "paymentMethod": "credit_card",
    "walletAddress": "0xYourWalletAddress",
    "redirectUrl": "https://yourapp.com/onramp/callback"
  }'

Step 5: Track Order Status

After the user completes payment, poll the order status:

async function pollOnrampStatus(orderUid: string) {
  while (true) {
    const status = await client.getOnrampStatus({ orderUid });

    console.log("Status:", status.status);

    switch (status.status) {
      case "PENDING":
        console.log("Waiting for payment...");
        break;
      case "PAYMENT_RECEIVED":
        console.log("Payment received, processing...");
        break;
      case "CRYPTO_SENT":
        console.log("Crypto sent to wallet!");
        console.log("Tx hash:", status.txHash);
        break;
      case "COMPLETED":
        console.log("Order complete!");
        return status;
      case "FAILED":
        console.error("Order failed:", status.failureReason);
        throw new Error(status.failureReason);
      case "REFUNDED":
        console.log("Payment was refunded");
        return status;
    }

    await new Promise((r) => setTimeout(r, 10000));
  }
}

curl "https://api.hypermid.io/v1/onramp/status?orderUid=ord_abc123" \
  -H "X-API-Key: your-api-key"

Complete Example

import { Hypermid } from "@hypermid/sdk";

const client = new Hypermid({ apiKey: process.env.HYPERMID_API_KEY });

async function buyEthWithUsd(walletAddress: string, usdAmount: number) {
  // 1. Check available assets
  const assets = await client.getOnrampAssets();
  const ethAsset = assets.assets.find(
    (a) => a.symbol === "ETH" && a.chainId === 1
  );

  if (!ethAsset) throw new Error("ETH not available for purchase");

  // 2. Get a quote
  const quote = await client.getOnrampQuote({
    fiatCurrency: "USD",
    cryptoAsset: "ETH",
    chainId: 1,
    fiatAmount: usdAmount,
    paymentMethod: "credit_card",
    walletAddress,
  });

  console.log(`$${usdAmount} USD = ${quote.cryptoAmount} ETH`);
  console.log(`Fees: $${quote.fees.totalFee} USD`);

  // 3. Create checkout
  const checkout = await client.createOnrampCheckout({
    fiatCurrency: "USD",
    cryptoAsset: "ETH",
    chainId: 1,
    fiatAmount: usdAmount,
    paymentMethod: "credit_card",
    walletAddress,
    redirectUrl: "https://yourapp.com/onramp/complete",
  });

  // 4. Return checkout URL for the frontend to redirect
  return {
    checkoutUrl: checkout.checkoutUrl,
    orderUid: checkout.orderUid,
  };
}

Best Practices

The fiat on-ramp involves real money. Always show users a clear summary of fees, exchange rates, and the expected crypto amount before redirecting to checkout.

Show fees transparently — Display the breakdown of network fees, processing fees, and exchange rate before the user proceeds.
Use webhooks for production — Instead of polling, configure a webhook to receive order status updates automatically.
Handle KYC requirements — Some jurisdictions and amounts may require additional KYC verification. The checkout flow handles this automatically, but inform users they may need to verify their identity.
Set appropriate redirect URLs — The redirectUrl should point to a page in your app that shows the order status and provides a good user experience.
Respect minimum/maximum amounts — Check the asset’s minAmount and maxAmount from the assets endpoint before requesting a quote.

Getting Started

Guides

Resources

Flow Overview

Step 1: Get Configuration

Step 2: Get Available Assets

Step 3: Get a Quote

Step 4: Create Checkout Session

Step 5: Track Order Status

Complete Example

Best Practices

​Flow Overview

​Step 1: Get Configuration

​Step 2: Get Available Assets

​Step 3: Get a Quote

​Step 4: Create Checkout Session

​Step 5: Track Order Status

​Complete Example

​Best Practices

Flow Overview

Step 1: Get Configuration

Step 2: Get Available Assets

Step 3: Get a Quote

Step 4: Create Checkout Session

Step 5: Track Order Status

Complete Example

Best Practices