Skip to main content

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