Skip to main content

Standard integration

Providers can integrate into the MetaMask Fiat On-Ramp using the standard integration method by implementing the following technical specification.

The web server specification uses OpenAPI, which allows the provider to generate a sample server quickly using third party tools such as Swagger Editor.

Four endpoints must be implemented:

important

We expect the host url to be the same for all endpoints listed below.

EndpointPathTypeInvocationDescription
Configuration/configurationGETServerReturns data allowing the On-Ramp to update the user experience based on what the provider allows the user to do, without any communication with the provider web server.
Quote/quoteGETClient (preferred) or ServerCalled when a user requests a quote.
Buy/buyGETClient (preferred) or ServerCalled when a user must be shown the provider buy widget.
Single order/orders/{orderId}GETClient (preferred) or ServerAllows the MetaMask mobile app or browser extension to retrieve order details for a single user.
All orders/ordersGETServerAllows the On-Ramp back end to retrieve all MetaMask orders to generate business intelligence analytics.

All parameters and output formats are described in the OpenAPI specification.

Configuration​

This endpoint is regularly called by the MetaMask servers. It's never called by the MetaMask mobile app or browser extension.

If the requirements of the provider integration are the following:

  • Available in the US
  • Allows fiat USD
  • Allows purchase of mainnet ETH
  • Allows debit or credit card payments
  • Prevents users from buying less than $10 or more than $50,000
  • Doesn't show up in the quotes screen

Then the configuration endpoint must return:

{
  "version": "1.0.0",
  "updatedAt": "2022-07-13T00:00:00",
  "features": {
    "orderCustomId": {
      "enabled": true
    },
    "quotes": {
      "enabled": false
    },
    "allOrders": {
      "enabled": true
    }
  },
  "countries": [
    {
      "id": "us"
    }
  ],
  "payments": [
    {
      "id": "debit-credit-card"
    }
  ],
  "fiat": [
    {
      "id": "USD",
      "paymentLimits": [
        {
          "id": "debit-credit-card",
          "min": 10,
          "max": 50000
        }
      ]
    }
  ],
  "crypto": [
    {
      "id": "eth",
      "address": "0x0000000000000000000000000000000000000000",
      "network": "1"
    }
  ]
}

unsupported field​

The payments, fiat, and crypto configurations allow using an unsupported field. This field describes restrictions on otherwise supported regions, payment methods, fiat currencies, or cryptocurrencies.

important

If a payment method is supported by many regions but you only want it to appear for a certain subset it is important to add those unsupported regions to the unsupported field.

If USD and EUR credit cards are supported, and SEPA is supported for EUR but not for USD, you can use the following definition:

payments: [
  {
    "id": "debit-credit-card"
  },
  {
    "id": "sepa-bank-transfer"
  }
],
fiat: [
  {
    "id": "USD",
    "unsupported": [
      "payment": "sepa-bank-transfer"
    ]
  },
  {
    "id": "EUR",
  }
]
important

If a country or a state isn't supported, just don't include it in the countries field of the configuration endpoint. Use the unsupported region field to restrict fiat, crypto, or payment methods from being used in a specific region that you support for other parameters.

Quote​

This endpoint is called each time MetaMask wants to fetch a quote from the provider to display it to the user.

Buy​

This endpoint is called each time MetaMask wants to redirect a user to the provider buy web page.

This endpoint takes parameters in a format owned by the aggregator, and displays the widget. The widget initial state reflects the value of the parameters. This endpoint can render the widget directly or perform an HTTP redirection to a widget hosted somewhere else. In the latter case, parameters can be translated to a provider-specific format in the redirection URL.

Orders​

Single order​

This endpoint is called each time MetaMask must refresh the order status. Once the status COMPLETED, FAILED, or CANCELED is reached for a specific order, no more calls are made for it.

All orders​

This endpoint can only be called by the MetaMask servers, with strong authentication. The authentication type is specified in the Configuration endpoint, and only OAuth is currently supported.

It returns all orders associated with the authenticated account.