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

200

Content type

application/json

{"version": "1.0.0",
"updatedAt": "2022-07-13T09:44:34.030Z",
"features": {"quotes": {"enabled": false
},
"buy": {"enable": true,
"authentication": {"scheme": "OAUTH",
"oauth": {"audience": "https://www.cypto-provider-example.com/oauth/audience"
}
},
"redirectOrderId": ["orderId"
],
"orderCustomId": true,
"browser": "APP_BROWSER",
"userAgent": ""
},
"orderTracking": {"enabled": true
},
"orderAnalytics": {"enabled": true
}
},
"countries": [{"id": "us"
}
],
"payments": [{"id": "debit-credit-card"
}
],
"fiat": [{"id": "USD",
"paymentLimits": [{"id": "debit-credit-card",
"min": "10",
"max": "50000"
}
],
"unsupported": [ ]
}
],
"crypto": [{"id": "eth",
"address": "0x0000000000000000000000000000000000000000",
"network": "1",
"paymentLimits": [{"id": "ach_bank_transfer",
"min": "10",
"max": "1000"
}
],
"payoutLimits": [{"id": "ach_bank_transfer",
"min": ".01",
"max": "10"
}
],
"unsupported": [{"feature": "sell",
"region": "us-ca"
}
]
}
]
}

Retrieves the full provider sell 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

200

Content type

application/json

{"version": "1.0.0",
"updatedAt": "2022-07-13T09:44:34.030Z",
"features": {"quotes": {"enabled": false
},
"buy": {"enable": true,
"authentication": {"scheme": "OAUTH",
"oauth": {"audience": "https://www.cypto-provider-example.com/oauth/audience"
}
},
"redirectOrderId": ["orderId"
],
"orderCustomId": true,
"browser": "APP_BROWSER",
"userAgent": ""
},
"orderTracking": {"enabled": true
},
"orderAnalytics": {"enabled": true
}
},
"countries": [{"id": "us"
}
],
"payments": [{"id": "debit-credit-card"
}
],
"fiat": [{"id": "USD",
"paymentLimits": [{"id": "debit-credit-card",
"min": "10",
"max": "50000"
}
],
"unsupported": [ ]
}
],
"crypto": [{"id": "eth",
"address": "0x0000000000000000000000000000000000000000",
"network": "1",
"paymentLimits": [{"id": "ach_bank_transfer",
"min": "10",
"max": "1000"
}
],
"payoutLimits": [{"id": "ach_bank_transfer",
"min": ".01",
"max": "10"
}
],
"unsupported": [{"feature": "sell",
"region": "us-ca"
}
]
}
]
}

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
walletAddress	string The user wallet address the crypto will be sent to.

Responses

Response samples

200
400

Content type

application/json

{"processingFee": "string",
"networkFee": "string",
"amountOut": "string",
"options": {"isNativeApplePay": false
}
}

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

200
400

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

200
400

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

200

Content type

application/json

{"id": "cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"customId": "p2nf67p1312nffgmubisg77ego4hrhx6lrxh21hd3e558qxsx57g9j5p0u7nl7hz",
"userId": "user-52324447448",
"link": "https://www.crypto-provider-example.com/order/cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"crypto": {"id": "eth",
"address": "0x0000000000000000000000000000000000000000",
"network": "1"
},
"fiatAmountIn": "205",
"fiatAmountInUsd": "205",
"cryptoAmountOut": "0.128311231723668931",
"fiat": "USD",
"payment": "debit-credit-card",
"providerPayment": "Mastercard",
"exchangeRate": "0.0006415561586183447",
"processingFees": [{"label": "Provider fees",
"fiatAmount": "1.3"
}
],
"networkFees": [{"label": "Ethereum blockchain transaction fees",
"fiatAmount": "2.7"
}
],
"partnerFees": [{"label": "MetaMask fees",
"fiatAmount": "1"
}
],
"region": "US-AL",
"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

200
400

Content type

application/json

[{"id": "cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"customId": "p2nf67p1312nffgmubisg77ego4hrhx6lrxh21hd3e558qxsx57g9j5p0u7nl7hz",
"userId": "user-52324447448",
"link": "https://www.crypto-provider-example.com/order/cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"crypto": {"id": "eth",
"address": "0x0000000000000000000000000000000000000000",
"network": "1"
},
"fiatAmountIn": "205",
"fiatAmountInUsd": "205",
"cryptoAmountOut": "0.128311231723668931",
"fiat": "USD",
"payment": "debit-credit-card",
"providerPayment": "Mastercard",
"exchangeRate": "0.0006415561586183447",
"processingFees": [{"label": "Provider fees",
"fiatAmount": "1.3"
}
],
"networkFees": [{"label": "Ethereum blockchain transaction fees",
"fiatAmount": "2.7"
}
],
"partnerFees": [{"label": "MetaMask fees",
"fiatAmount": "1"
}
],
"region": "US-AL",
"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"
}
]

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

200

Content type

application/json

{"id": "cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"userId": "user-52324447448",
"link": "https://www.crypto-provider-example.com/order/cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"crypto": {"id": "eth",
"address": "0x0000000000000000000000000000000000000000",
"network": "1"
},
"fiatAmountOut": "205",
"fiatAmountOutUsd": "205",
"cryptoAmountIn": "0.128311231723668931",
"fiat": "USD",
"payment": "debit-credit-card",
"providerPayment": "Mastercard",
"exchangeRate": "0.0006415561586183447",
"processingFees": [{"label": "Provider fees",
"fiatAmount": "1.3"
}
],
"partnerFees": [{"label": "MetaMask fees",
"fiatAmount": "1"
}
],
"createdAt": "2022-08-22T09:10:43.724Z",
"updatedAt": "2022-08-22T09:13:56.165Z",
"region": "US-AL",
"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

200
400

Content type

application/json

[{"id": "cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"customId": "p2nf67p1312nffgmubisg77ego4hrhx6lrxh21hd3e558qxsx57g9j5p0u7nl7hz",
"userId": "user-52324447448",
"link": "https://www.crypto-provider-example.com/order/cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"crypto": {"id": "eth",
"address": "0x0000000000000000000000000000000000000000",
"network": "1"
},
"fiatAmountIn": "205",
"fiatAmountInUsd": "205",
"cryptoAmountOut": "0.128311231723668931",
"fiat": "USD",
"payment": "debit-credit-card",
"providerPayment": "Mastercard",
"exchangeRate": "0.0006415561586183447",
"processingFees": [{"label": "Provider fees",
"fiatAmount": "1.3"
}
],
"networkFees": [{"label": "Ethereum blockchain transaction fees",
"fiatAmount": "2.7"
}
],
"partnerFees": [{"label": "MetaMask fees",
"fiatAmount": "1"
}
],
"region": "US-AL",
"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 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

200
400

Content type

application/json

[{"id": "cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"userId": "user-52324447448",
"link": "https://www.crypto-provider-example.com/order/cd7ad58d-0fbb-4ed5-9fdd-832c1709ce85",
"crypto": {"id": "eth",
"address": "0x0000000000000000000000000000000000000000",
"network": "1"
},
"fiatAmountOut": "205",
"fiatAmountOutUsd": "205",
"cryptoAmountIn": "0.128311231723668931",
"fiat": "USD",
"payment": "debit-credit-card",
"providerPayment": "Mastercard",
"exchangeRate": "0.0006415561586183447",
"processingFees": [{"label": "Provider fees",
"fiatAmount": "1.3"
}
],
"partnerFees": [{"label": "MetaMask fees",
"fiatAmount": "1"
}
],
"createdAt": "2022-08-22T09:10:43.724Z",
"updatedAt": "2022-08-22T09:13:56.165Z",
"region": "US-AL",
"transactionHash": "0x5ea06c4724e8119704a1b57c918acf31742eb06cdf3f8678fdb17f41bbaf968e",
"walletAddress": "0x75b8d4d81377d4b0f11798779563462264914a24",
"providerWalletAddress": "0x75b8d4d81377d4b0f11798779563462264914a24",
"status": "PENDING",
"statusCode": "PROVIDER-PENDING-ORDER",
"statusReason": "The order is currently being processed.",
"partnerAccountId": "MetaMask"
}
]

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

200
400

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>