Skip to main content

Ramp Network REST API Reference

This page describes version 1 of our available REST API (we recommend to refer to the latest version which can be found here).

General info​

API base path: https://api.ramp.network/api

All request and response bodies should be in JSON, with corresponding application/json headers.

If an error is returned, the response body is also a JSON object, with a code property describing the problem, and optionally more properties providing additional details.

ℹ️ All endpoints are subject to rate limiting.

Available assets and prices​

Endpoint: GET /host-api/assets

Query parameters:

  • hostApiKey (optional): if you have a custom integration, provide the key to access your enabled features.
    • If provided, the response will contain an enabledFeatures property with a list of the features enabled.
    • Contact us at partner@ramp.network if you want a custom integration :)
  • userIp (optional): string representing an IP address.
    • The assets field in the response will include only the assets available in the geolocation associated with the provided IP.
  • onlyEnabled (optional): boolean parameter - if it's true, only assets with enabled: true will be returned. Use this param to filter assets that are temporarily disabled, for example due to maintenance.
  • omitHidden (optional): boolean parameter - if it's true, assets with hidden: true will not be returned.

Response contents​

interface HostAssetsConfig {
  assets: AssetInfo[];
  enabledFeatures?: string[];

  minPurchaseAmountEur: number;
  maxPurchaseAmountEur: number;
  minFeeAmountEur: number;
  // Final fee percentage depends on the payment method and purchase size.
  minFeePercent: number;
  maxFeePercent: number;
}

interface AssetInfo {
  // Asset symbol, e.g. ETH, DAI, BTC
  symbol: string;
  // Asset descriptive name, e.g. Ethereum
  name: string;
  // Number of decimal places to convert units to whole coins
  decimals: number;
  // Asset type -- blockchain type for native assets (e.g. ETH, BTC, ELROND), or a token standard (e.g. ERC20)
  type: string;
  // Token contract address, if applicable (if the asset is not the chain native asset)
  address?: string;
  logoUrl: string;
  enabled: boolean;
  hidden: boolean;

  // Last known price for one whole asset unit (1 ETH/DAI/...), in EUR
  priceEur: number;
  priceUpdateTs: Date;

  // Approximate price of a single whole asset unit (1 ETH/DAI/...) per currency code. Please note that the actual price may vary
  price: Dictionary<number>;
  // Asset-specific purchase limits, -1 means unlimited (global limits are used)
  minPurchaseAmountEur: number;
  maxPurchaseAmountEur: number;
  minPurchaseCryptoAmount: string; // in wei/units
  // Network fee for the asset added on top of Ramp Network's fee
  networkFeeEur: number;
  networkParamsUpdatedAt: Date;
}

Example​

Request:

curl -X GET https://api.ramp.network/api/host-api/assets

Response:

{
  "minPurchaseAmountEur": 10,
  "maxPurchaseAmountEur": 10000,
  "minFeeAmountEur": 3,
  "minFeePercent": 0.5,
  "maxFeePercent": 2.99,
  "assets": [
    {
      "address": "0x0000....",
      "symbol": "ETH",
      "name": "Ether",
      "decimals": 18,
      "type": "ETH",
      "enabled": true,
      "logoUrl": "https://assets.ramp.network/crypto-assets/eth.svg",
      "hidden": false,
      "priceEur": 146.204351612996,
      "priceUpdateTs": "2020-01-24T12:47:08.475Z",
      "networkFeeEur": 0.01,
      "networkParamsUpdatedAt": "2020-01-24T12:47:08.475Z",
      "price": {
        "EUR": 146.204351612996,
        "PLN": 34.36787710229498,
        "USD": 130.94295070798083,
        "GBP": 123.30407161114876
      },
      "minPurchaseAmountEur": -1,
      "maxPurchaseAmountEur": -1,
      "minPurchaseCryptoAmount": "-1"
    },
    {
      "address": "0x0000....",
      "symbol": "DAI",
      "name": "Multi-Collateral DAI",
      "decimals": 18,
      "type": "ERC20",
      "enabled": true,
      "logoUrl": "https://assets.ramp.network/crypto-assets/dai.svg",
      "hidden": false,
      "priceEur": 0.906651167794897,
      "priceUpdateTs": "2020-01-24T12:47:08.494Z",
      "networkFeeEur": 0.01,
      "networkParamsUpdatedAt": "2020-01-24T12:47:08.475Z",
      "price": {
        "EUR": 0.906651167794897,
        "PLN": 0.21312413458052976,
        "USD": 0.8120112559176902,
        "GBP": 0.7646405820808438
      },
      "minPurchaseAmountEur": -1,
      "maxPurchaseAmountEur": 15,
      "minPurchaseCryptoAmount": "-1"
    }
  ]
}

Available countries​

Endpoint: GET /host-api/countries

Returns all currently enabled countries.

Response contents​

An array of CountryInfo objects.

interface CountryInfo {
    code!: string;  // ISO 3166 alpha-2 country code
    name!: string;
    cardPaymentsEnabled!: boolean; // deprecated and hardcoded to true
    // Default currency (ISO 4217 currency code) used for this country
    mainCurrencyCode!: string;
    // `null` means all assets available, empty list (`[]`) means no assets available.
    supportedAssets?: string[];
}

Example​

Request:

curl -X GET https://api.ramp.network/api/host-api/countries

Response:

[
  {
    "cardPaymentsEnabled": true,
    "code": "at",
    "mainCurrencyCode": "EUR",
    "name": "Austria",
    "supportedAssets": null
  },
  {
    "cardPaymentsEnabled": true,
    "code": "be",
    "mainCurrencyCode": "EUR",
    "name": "Belgium",
    "supportedAssets": null
  },
  {
    "cardPaymentsEnabled": true,
    "code": "hr",
    "mainCurrencyCode": "EUR",
    "name": "Croatia",
    "supportedAssets": null
  }
]

Purchase quotation​

Endpoint: POST /host-api/quote

Query parameters:

  • hostApiKey: the integration key you've received from us.

Request body:

interface QuoteRequestBody {
  cryptoAssetSymbol: string;
  fiatCurrency: string;

  /*
   * Although fiatValue and cryptoAmount are not both required, you need to pass one of them.
   */
  cryptoAmount?: string;
  fiatValue?: number;

  /*
   * When paymentMethodType is not provided the result is calculated for the payment method with the lowest fee that supports the currency given in the fiatCurrency parameter.
   */
  paymentMethodType?: PaymentMethodName;
}

enum PaymentMethodName {
  MANUAL_BANK_TRANSFER = 'MANUAL_BANK_TRANSFER',
  AUTO_BANK_TRANSFER = 'AUTO_BANK_TRANSFER',
  CARD_PAYMENT = 'CARD_PAYMENT',
  APPLE_PAY = 'APPLE_PAY',
  GOOGLE_PAY = 'GOOGLE_PAY',
  PIX = 'PIX',
}

Response contents​

For convenience, the QuoteResult object is a subset of the RampPurchase object.

interface PublicAssetDetails {
  address: string | null; // only defined for tokens
  symbol: string;
  name: string;
  decimals: number;
}

interface QuoteResult {
  cryptoAssetSymbol: string;
  fiatCurrency: string; // three-letter currency code
  cryptoAmount: string; // number-string, in wei or token units
  fiatValue: number; // total value the user pays for the purchase, in fiatCurrency
  paymentMethodType: PublicPaymentMethodName; // type of payment method used to pay for the swap - see values below
  asset: PublicAssetDetails; // object describing basic asset properties
  assetExchangeRate: number; // price of 1 whole token of purchased asset, in fiatCurrency
  assetExchangeRateEur: number; // price of 1 whole token of purchased asset, in EUR
  fiatExchangeRateEur: number; // price of fiatCurrency in EUR
  baseRampFee: number; // base Ramp Network fee before any modifications, in fiatCurrency
  networkFee: number; // network fee for transferring the purchased asset, in fiatCurrency
  appliedFee: number; // final fee the user pays (included in fiatValue), in fiatCurrency
}

Example​

Request

curl -X POST https://api.ramp.network/api/host-api/quote\?hostApiKey\=xxxxxxxxx -H 'content-type: application/json' -d '{
        "cryptoAssetSymbol": "ETH",
        "fiatValue": 100,
        "fiatCurrency": "GBP",
        "paymentMethodType": "APPLE_PAY"
}'

Response

{
  "cryptoAssetSymbol": "ETH",
  "asset": {
    "address": null,
    "symbol": "ETH",
    "name": "Ether",
    "decimals": 18,
    "type": "ETH"
  },
  "fiatCurrency": "GBP",
  "cryptoAmount": "55031537596175593",
  "fiatValue": 100,
  "paymentMethodType": "APPLE_PAY",
  "assetExchangeRate": 1775.695251998649,
  "assetExchangeRateEur": 2055.60491809005,
  "fiatExchangeRateEur": 1.15763384273081,
  "baseRampFee": 2.8338579605717102,
  "networkFee": 1.727662000000003,
  "appliedFee": 2.2807599802858567
}

Possible error response in case unsupported fiatCurrency and paymentMethodType combination was requested

{
    "currency": "EUR",
    "paymentMethodType": "PIX",
    "code": "SERVICES.HOST_API.UNSUPPORTED_CURRENCY_FOR_REQUESTED_PAYMENT_METHOD",
    "statusCode": 400
}

Purchase status​

Endpoint: GET /host-api/purchase/{id}

Path parameter: id (required): id of the purchase, received from a SDK event or a webhook call.

Query parameter: secret (required): the purchaseViewToken received with the same purchase created event.

Response contents​

A single RampPurchase object, the same that's used in webhook calls.

Example​

Request:

curl -X GET https://api.ramp.network/api/host-api/purchase/123?secret=xxxxxxxx

Response:

{
  "id": "123",
  "endTime": "2019-10-29T15:41:41.065Z",
  "asset": {
    "address": null,
    "symbol": "ETH",
    "name": "Ether",
    "decimals": 18,
    "type": "ETH"
  },
  "cryptoAmount": "30000000000000000",
  "fiatCurrency": "GBP",
  "fiatValue": 0.04,
  "assetExchangeRate": 1.27378941587846,
  "assetExchangeRateEur": 1.51277630353432,
  "baseRampFee": 0.09892653257425743,
  "networkFee": 0.008420210000000001,
  "appliedFee": 0.10734674257425743,
  "purchaseViewToken": "...",
  "receiverAddress": "0x2222222222222222222222222222222222222222",
  "createdAt": "2019-10-24T14:41:39.372Z",
  "updatedAt": "2019-10-24T15:41:41.065Z",
  "status": "INITIALIZED",
  "finalTxHash": null,
  "paymentMethodType": "MANUAL_BANK_TRANSFER",
  "purchaseViewToken": "4eb9ndrsb59erawh"
}