Ramp Instant REST API Reference

General info

API base path: https://api-instant.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.

Available assets and prices

Endpoint: GET /host-api/assets

Query parameters:

  • currencies (optional): comma-separated list of currency codes for which we should return asset prices.
    • If not provided, all available currencies will be used.
    • If provided, only available currencies from the list will be used.
    • If no requested currencies are available, an error is returned, with code SERVICES.HOST_API.NO_CURRENCIES_AVAILABLE.
  • 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 :)

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;
// Last known price for one whole asset unit (1 ETH/DAI/...), in EUR
priceEur: number;
priceUpdateTs: Date;
// Price of a single whole asset unit (1 ETH/DAI/...) per currency code
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;
}

Example

Request:

curl -X GET https://api-instant.ramp.network/api/host-api/assets?currencies=GBP

Response:

{
"minPurchaseAmountEur": 10,
"maxPurchaseAmountEur": 10000,
"minFeeAmountEur": 3,
"minFeePercent": 0.5,
"maxFeePercent": 2.99,
"assets": [
{
"address": "0x0000....",
"symbol": "ETH",
"name": "Ether",
"decimals": 18,
"priceEur": 146.204351612996,
"priceUpdateTs": "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,
"priceEur": 0.906651167794897,
"priceUpdateTs": "2020-01-24T12:47:08.494Z",
"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;
// 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-instant.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;
paymentMethodType: PaymentMethodName;
}
enum PaymentMethodName {
MANUAL_BANK_TRANSFER = 'MANUAL_BANK_TRANSFER',
AUTO_BANK_TRANSFER = 'AUTO_BANK_TRANSFER',
CARD_PAYMENT = 'CARD_PAYMENT',
APPLE_PAY = 'APPLE_PAY',
}

Response contents

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

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
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-instant.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",
"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
}

Purchase status

Endpoint: GET /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-instant.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
},
"escrowAddress": "0x528bfce01f58390c9eb81419061cd617896348be",
"cryptoAmount": "30000000000000000",
"fiatCurrency": "GBP",
"fiatValue": 0.04,
"assetExchangeRate": 1.27378941587846,
"poolFee": 0.000573205237145307,
"rampFee": 0.000573205237145307,
"purchaseViewToken": "...",
"receiverAddress": "0x2222222222222222222222222222222222222222",
"createdAt": "2019-10-24T14:41:39.372Z",
"updatedAt": "2019-10-24T15:41:41.065Z",
"status": "INITIALIZED",
"finalTxHash": null,
}