Skip to main content

Sample Provider for MetaMask On-Ramp Aggregator (1.4.0)

Download OpenAPI specification:Download

This is a swagger file for the a sample provider of the MetaMask On-Ramp Aggregator

Configuration

Endpoints called by the MetaMask back end outside of any user flow

Retrieves the full provider configuration

This data allows the aggregator to adapt it behavior to the provider capabilities. For example, it describes under which conditions a cryptocurrency is displayed to the user (based on their region, payment method, etc.)

Authorizations:
Noneoauthapi_key

Responses

Response samples

Content type
application/json
{
  • "version": "1.0.0",
  • "updatedAt": "2022-07-13T09:44:34.030Z",
  • "features": {
    },
  • "countries": [
    ],
  • "payments": [
    ],
  • "fiat": [
    ],
  • "crypto": [
    ]
}

Quotes

Allows MetaMask to retrieve a quote to display to the user

Returns a quote

This endpoint takes parameters in a format owned by the Aggregator, and returns the associated quote. This endpoint will never be called if the /configuration feature "quotes" is disabled.

Authorizations:
Noneoauthapi_key
query Parameters
region
required
string

The region of the user. Can be a country ID (ex: "us") or state ID (ex: "us-al")

payment
required
string

The payment method chosen by the user. Supported values are "debit-credit-card", "apple-pay", "sepa-bank-transfer", "gbp-bank-transfer", "ach-bank-transfer", "upi", and "pix"

crypto
required
string

The crypto currency the user wants to buy. It needs to be a crypto ID defined in the /configuration endpoint

fiat
required
string

The fiat currency the user wants to use to buy crypto. It needs to be a fiat ID defined in the /configuration endpoint

amount
required
string

The amount of fiat currency the user wants to use to buy crypto. Use a quoted float number (ex: "1.20")

partnerAccountId
required
string <uri>

An ID identifying MetaMask and associating subsequent order with it

Responses

Response samples

Content type
application/json
{
  • "processingFee": "string",
  • "networkFee": "string",
  • "amountOut": "string"
}

Returns an off-ramp quote

This endpoint takes parameters in a format owned by the Aggregator, and returns the associated quote. This endpoint will never be called if the /configuration feature "sell-quotes" is disabled.

Authorizations:
Noneoauthapi_key
query Parameters
region
required
string

The region of the user. Can be a country ID (ex: "us") or state ID (ex: "us-al")

payment
required
string

The payment method chosen by the user. Supported values are "debit-credit-card", "apple-pay", "sepa-bank-transfer", "gbp-bank-transfer", "ach-bank-transfer", "upi", and "pix"

crypto
required
string

The crypto currency the user wants to buy. It needs to be a crypto ID defined in the /configuration endpoint

fiat
required
string

The fiat currency the user wants to use to buy crypto. It needs to be a fiat ID defined in the /configuration endpoint

amount
required
string

The amount of crypto currency the user wants to sell. Use a quoted float number (ex: "1.20")

partnerAccountId
required
string <uri>

An ID identifying MetaMask and associating subsequent order with it

recurringFrequency
string (frequency)
Enum: "weekly" "monthly"

The frequency of the recurring order. If not specified, the quote is for a one-time order.

Responses

Response samples

Content type
application/json
{
  • "processingFee": "string",
  • "networkFee": "string",
  • "amountOut": "string"
}

Buy

Allows a WebView to display the Buy widget

Displays the widget

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

Authorizations:
Noneoauthapi_key
query Parameters
region
required
string

The region of the user. Can be a country ID (ex: "us") or state ID (ex: "us-al")

payment
required
string

The payment method chosen by the user. Supported values are "debit-credit-card", "apple-pay", "sepa-bank-transfer", "gbp-bank-transfer", "ach-bank-transfer", "upi", and "pix"

crypto
required
string

The crypto currency the user wants to buy. It needs to be a crypto ID defined in the /configuration endpoint

fiat
required
string

The fiat currency the user wants to use to buy crypto. It needs to be a fiat ID defined in the /configuration endpoint

amount
required
string

The amount of fiat currency the user wants to use to buy crypto.

walletAddress
required
string

The user wallet address the crypto will be sent to.

orderCustomId
string

A client-defined randomly generated 64-character string used to retrieve the order in case the redirection goes wrong. Used characters: lower case (a-z), upper case (A-Z) and digits (0-9). This is only used if the "orderCustomId" feature is enabled in the /configuration endpoint.

redirectUrl
required
string <uri>

The URL the user will be redirected to after the buy flow has been performed in the provider widget.

partnerAccountId
required
string <uri>

An ID identifying MetaMask and associating subsequent order with it

Responses

Response samples

Content type
text/html
<html>
  <head>
    <title>
      Buy crypto currency
    </title>
  </head>
  <body>
    This is a webpage allowing me to buy crypto currency.
  </body>
</html>

Orders

Track orders details

Retrieves the status of a single order

Authorizations:
Noneoauthapi_key
path Parameters
orderId
required
string

The ID of the order to retrieve. If the "orderCustomId" feature is enable in the /configuration endpoint, this can be a custom ID previously provided by MetaMask.

query Parameters
walletAddress
required
string

The wallet address supposedly associated with the order. This is used as a security measure preventing random order browsing.

Responses

Response samples

Content type
application/json
{
  • "id": "cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
  • "customId": "p2nf67p1312nffgmubisg77ego4hrhx6lrxh21hd3e558qxsx57g9j5p0u7nl7hz",
  • "userId": "user-52324447448",
  • "crypto": {
    },
  • "fiatAmountIn": "205",
  • "fiatAmountInUsd": "205",
  • "cryptoAmountOut": "0.128311231723668931",
  • "fiat": "USD",
  • "payment": "debit-credit-card",
  • "providerPayment": "Mastercard",
  • "exchangeRate": "0.0006415561586183447",
  • "processingFees": [
    ],
  • "networkFees": [
    ],
  • "partnerFees": [
    ],
  • "createdAt": "2022-08-22T09:10:43.724Z",
  • "updatedAt": "2022-08-22T09:13:56.165Z",
  • "transactionHash": "0x5ea06c4724e8119704a1b57c918acf31742eb06cdf3f8678fdb17f41bbaf968e",
  • "walletAddress": "0x75b8d4d81377d4b0f11798779563462264914a24",
  • "status": "PENDING",
  • "statusCode": "PROVIDER-PENDING-ORDER",
  • "statusReason": "The order is currently being processed.",
  • "partnerAccountId": "MetaMask",
  • "orderType": "BUY"
}

Securely retrieves a list of orders associated to a recurring order

This endpoint retrieves a list of orders associated to a recurring order. An order dataset is defined by start and end, and can be browsed with skip and limit.

Authorizations:
Noneoauthapi_key
path Parameters
orderId
required
string

The ID of the initial order associated to the orders to retrieve.

query Parameters
walletAddress
required
string

The wallet address supposedly associated with the order. This is used as a security measure preventing random order browsing.

start
required
string <date>

The start date of the dataset. This is inclusive: orders created at this exact date should be included.

end
required
string <date>

The end date of the dataset. This is inclusive: orders created at this exact date should be included.

skip
required
integer

The number of orders to skip in the dataset.

limit
required
integer

The maximum number of orders of the dataset to include in the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieves the status of a single off-ramp order

Authorizations:
Noneoauthapi_key
path Parameters
orderId
required
string

The ID of the order to retrieve. If the "orderCustomId" feature is enable in the /configuration endpoint, this can be a custom ID previously provided by MetaMask.

query Parameters
walletAddress
required
string

The wallet address supposedly associated with the order. This is used as a security measure preventing random order browsing.

Responses

Response samples

Content type
application/json
{
  • "id": "cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
  • "userId": "user-52324447448",
  • "crypto": {
    },
  • "fiatAmountOut": "205",
  • "fiatAmountOutUsd": "205",
  • "cryptoAmountIn": "0.128311231723668931",
  • "fiat": "USD",
  • "payment": "debit-credit-card",
  • "providerPayment": "Mastercard",
  • "exchangeRate": "0.0006415561586183447",
  • "processingFees": [
    ],
  • "partnerFees": [
    ],
  • "createdAt": "2022-08-22T09:10:43.724Z",
  • "updatedAt": "2022-08-22T09:13:56.165Z",
  • "transactionHash": "0x5ea06c4724e8119704a1b57c918acf31742eb06cdf3f8678fdb17f41bbaf968e",
  • "walletAddress": "0x75b8d4d81377d4b0f11798779563462264914a24",
  • "providerWalletAddress": "0x75b8d4d81377d4b0f11798779563462264914a24",
  • "status": "PENDING",
  • "statusCode": "PROVIDER-PENDING-ORDER",
  • "statusReason": "The order is currently being processed.",
  • "partnerAccountId": "MetaMask"
}

Securely retrieves a list of orders

This endpoint retrieves a list of orders associated to MetaMask On-Ramp. Only MetaMask can access this aggregated data. An order dataset is defined by start and end, and can be browsed with skip and limit.

Authorizations:
Noneoauthapi_key
query Parameters
start
required
string <date>

The start date of the dataset. This is inclusive: orders created at this exact date should be included.

end
required
string <date>

The end date of the dataset. This is inclusive: orders created at this exact date should be included.

skip
required
integer

The number of orders to skip in the dataset.

limit
required
integer

The maximum number of orders of the dataset to include in the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Securely retrieves a list of off-ramp orders

This endpoint retrieves a list of orders associated to MetaMask On-Ramp. Only MetaMask can access this aggregated data. An order dataset is defined by start and end, and can be browsed with skip and limit.

Authorizations:
Noneoauthapi_key
query Parameters
start
required
string <date>

The start date of the dataset. This is inclusive: orders created at this exact date should be included.

end
required
string <date>

The end date of the dataset. This is inclusive: orders created at this exact date should be included.

skip
required
integer

The number of orders to skip in the dataset.

limit
required
integer

The maximum number of orders of the dataset to include in the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Sell

Displays the off-ramp widget

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

Authorizations:
Noneoauthapi_key
query Parameters
region
required
string

The region of the user. Can be a country ID (ex: "us") or state ID (ex: "us-al")

payment
required
string

The payment method chosen by the user. Supported values are "debit-credit-card", "apple-pay", "sepa-bank-transfer", "gbp-bank-transfer", "ach-bank-transfer", "upi", and "pix"

crypto
required
string

The crypto currency the user wants to buy. It needs to be a crypto ID defined in the /configuration endpoint

fiat
required
string

The fiat currency the user wants to use to buy crypto. It needs to be a fiat ID defined in the /configuration endpoint

amount
required
string

The amount of crypto currency the user wants to sell.

walletAddress
required
string

The user wallet address the user will use to send the crypto.

redirectUrl
required
string <uri>

The URL the user will be redirected to after the buy flow has been performed in the provider widget.

partnerAccountId
required
string <uri>

An ID identifying MetaMask and associating subsequent order with it

Responses

Response samples

Content type
text/html
<html>
  <head>
    <title>
      Buy crypto currency
    </title>
  </head>
  <body>
    This is a webpage allowing me to buy crypto currency.
  </body>
</html>