openapi: 3.0.2
info:
title: Sample Provider for MetaMask On-Ramp Aggregator
description: >-
This is a swagger file for the a sample provider of the MetaMask On-Ramp
Aggregator
version: 1.4.0
externalDocs:
description: MetaMask
url: https://metamask.io/
servers:
- url: /
tags:
- name: Configuration
description: Endpoints called by the MetaMask back end outside of any user flow
- name: Quotes
description: Allows MetaMask to retrieve a quote to display to the user
- name: Buy
description: Allows a WebView to display the Buy widget
- name: Orders
description: Track orders details
paths:
/configuration:
get:
tags:
- Configuration
summary: Retrieves the full provider configuration
description: >-
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.)
operationId: getConfiguration
security:
- {}
- oauth: []
- api_key: []
responses:
'200':
description: Valid response
content:
application/json:
schema:
$ref: '#/components/schemas/configuration'
/sell-configuration:
get:
tags:
- Configuration
summary: Retrieves the full provider sell configuration
description: >-
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.)
operationId: getSellConfiguration
security:
- {}
- oauth: []
- api_key: []
responses:
'200':
description: Valid response
content:
application/json:
schema:
$ref: '#/components/schemas/configuration'
/quote:
get:
tags:
- Quotes
summary: Returns a quote
description: >-
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.
operationId: getQuote
security:
- {}
- oauth: []
- api_key: []
parameters:
- name: region
in: query
description: >-
The region of the user. Can be a country ID (ex: "us") or state ID
(ex: "us-al")
required: true
schema:
type: string
- name: payment
in: query
description: >-
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"
required: true
schema:
type: string
- name: crypto
in: query
description: >-
The crypto currency the user wants to buy. It needs to be a crypto
ID defined in the /configuration endpoint
required: true
schema:
type: string
- name: fiat
in: query
description: >-
The fiat currency the user wants to use to buy crypto. It needs to
be a fiat ID defined in the /configuration endpoint
required: true
schema:
type: string
- name: amount
in: query
description: >-
The amount of fiat currency the user wants to use to buy crypto. Use
a quoted float number (ex: "1.20")
required: true
schema:
type: string
- name: partnerAccountId
in: query
description: An ID identifying MetaMask and associating subsequent order with it
required: true
schema:
type: string
format: uri
- name: walletAddress
in: query
description: The user wallet address the crypto will be sent to.
required: false
schema:
type: string
responses:
'200':
description: Valid response
content:
application/json:
schema:
type: object
properties:
processingFee:
type: string
description: >-
The fee received by the provider and MetaMask. It is
expressed in the quote fiat currency. Use a quoted float
number (ex: "1.20")
networkFee:
type: string
description: >-
The fee received by the network used to make the purchase.
It is expressed in the quote fiat currency. Use a quoted
float number (ex: "1.20")
amountOut:
type: string
description: >-
The amount of crypto currency the user will receive if
this quote is used to make a purchase. Use a quoted float
number (ex: "1.20")
options:
description: >-
Additional options for the users quote such as native
apple pay support.
type: object
properties:
isNativeApplePay:
type: boolean
default: false
required: false
description: Determines if the quote supports native apple pay
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/bad-request'
/sell-quote:
get:
tags:
- Quotes
summary: Returns an off-ramp quote
description: >-
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.
operationId: getSellQuote
security:
- {}
- oauth: []
- api_key: []
parameters:
- name: region
in: query
description: >-
The region of the user. Can be a country ID (ex: "us") or state ID
(ex: "us-al")
required: true
schema:
type: string
- name: payment
in: query
description: >-
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"
required: true
schema:
type: string
- name: crypto
in: query
description: >-
The crypto currency the user wants to sell. It needs to be a crypto
ID defined in the /configuration endpoint
required: true
schema:
type: string
- name: fiat
in: query
description: >-
The fiat currency the user wants to receive. It needs to be a fiat
ID defined in the /configuration endpoint
required: true
schema:
type: string
- name: amount
in: query
description: >-
The amount of crypto currency the user wants to sell. Use a quoted
float number (ex: "1.20")
required: true
schema:
type: string
- name: partnerAccountId
in: query
description: An ID identifying MetaMask and associating subsequent order with it
required: true
schema:
type: string
format: uri
- name: recurringFrequency
in: query
description: >-
The frequency of the recurring order. If not specified, the quote is
for a one-time order.
required: false
schema:
$ref: '#/components/schemas/frequency'
responses:
'200':
description: Valid response
content:
application/json:
schema:
type: object
properties:
processingFee:
type: string
description: >-
The fee received by the provider and MetaMask. It is
expressed in the quote fiat currency. Use a quoted float
number (ex: "1.20")
networkFee:
type: string
description: >-
The fee received by the network used to make the purchase.
It is expressed in the quote fiat currency. Use a quoted
float number (ex: "1.20")
amountOut:
type: string
description: >-
The amount of crypto currency the user will receive if
this quote is used to make a purchase. Use a quoted float
number (ex: "1.20")
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/bad-request'
/buy:
get:
tags:
- Buy
summary: Displays the widget
description: >-
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.
operationId: getBuy
security:
- {}
- oauth: []
- api_key: []
parameters:
- name: region
in: query
description: >-
The region of the user. Can be a country ID (ex: "us") or state ID
(ex: "us-al")
required: true
schema:
type: string
- name: payment
in: query
description: >-
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"
required: true
schema:
type: string
- name: crypto
in: query
description: >-
The crypto currency the user wants to buy. It needs to be a crypto
ID defined in the /configuration endpoint
required: true
schema:
type: string
- name: fiat
in: query
description: >-
The fiat currency the user wants to use to buy crypto. It needs to
be a fiat ID defined in the /configuration endpoint
required: true
schema:
type: string
- name: amount
in: query
description: The amount of fiat currency the user wants to use to buy crypto.
required: true
schema:
type: string
- name: walletAddress
in: query
description: The user wallet address the crypto will be sent to.
required: true
schema:
type: string
- name: orderCustomId
in: query
description: >-
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.
schema:
type: string
- name: redirectUrl
in: query
description: >-
The URL the user will be redirected to after the buy flow has been
performed in the provider widget.
required: true
schema:
type: string
format: uri
- name: partnerAccountId
in: query
description: An ID identifying MetaMask and associating subsequent order with it
required: true
schema:
type: string
format: uri
- name: hash
in: query
description: The hashed IP of the requesting user
required: false
schema:
type: string
responses:
'200':
description: >-
The widget is directly rendered by the endpoint. The MIME type
"text/html" is given as an example. Any MIME type browsers can
display as a webpage is valid.
content:
text/html:
example: |-
Buy crypto currency
This is a webpage allowing me to buy crypto currency.
'303':
description: >-
Redirects to another address actually rendering the widget. Specify
the redirected address in the "Location" HTTP header of the
response. See https://en.wikipedia.org/wiki/HTTP_303
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/bad-request'
/sell:
get:
tags:
- Sell
summary: Displays the off-ramp widget
description: >-
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.
operationId: getSell
security:
- {}
- oauth: []
- api_key: []
parameters:
- name: region
in: query
description: >-
The region of the user. Can be a country ID (ex: "us") or state ID
(ex: "us-al")
required: true
schema:
type: string
- name: payment
in: query
description: >-
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"
required: true
schema:
type: string
- name: crypto
in: query
description: >-
The crypto currency the user wants to sell. It needs to be a crypto
ID defined in the /configuration endpoint
required: true
schema:
type: string
- name: fiat
in: query
description: >-
The fiat currency the user wants to receive. It needs to be a fiat
ID defined in the /configuration endpoint
required: true
schema:
type: string
- name: amount
in: query
description: The amount of crypto currency the user wants to sell.
required: true
schema:
type: string
- name: walletAddress
in: query
description: The user wallet address the user will use to send the crypto.
required: true
schema:
type: string
- name: redirectUrl
in: query
description: >-
The URL the user will be redirected to after the sell flow has been
performed in the provider widget.
required: true
schema:
type: string
format: uri
- name: partnerAccountId
in: query
description: An ID identifying MetaMask and associating subsequent order with it
required: true
schema:
type: string
format: uri
- name: hash
in: query
description: The hashed IP of the requesting user
required: false
schema:
type: string
responses:
'200':
description: >-
The widget is directly rendered by the endpoint. The MIME type
"text/html" is given as an example. Any MIME type browsers can
display as a webpage is valid.
content:
text/html:
example: |-
Buy crypto currency
This is a webpage allowing me to buy crypto currency.
'303':
description: >-
Redirects to another address actually rendering the widget. Specify
the redirected address in the "Location" HTTP header of the
response. See https://en.wikipedia.org/wiki/HTTP_303
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/bad-request'
/orders/{orderId}:
get:
tags:
- Orders
summary: Retrieves the status of a single order
operationId: getSellOrder
security:
- {}
- oauth: []
- api_key: []
parameters:
- name: orderId
in: path
description: >-
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.
required: true
schema:
type: string
- name: walletAddress
in: query
description: >-
The wallet address supposedly associated with the order. This is
used as a security measure preventing random order browsing.
required: true
schema:
type: string
responses:
'200':
description: The widget is directly rendered by the endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/order'
'404':
description: >-
The order doesn't exist or is not associated to the right wallet
address.
content: {}
/orders/{orderId}/recurring:
get:
tags:
- Orders
summary: Securely retrieves a list of orders associated to a recurring order
description: >-
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`.
operationId: getRecurringOrders
security:
- {}
- oauth: []
- api_key: []
parameters:
- name: orderId
in: path
description: The ID of the initial order associated to the orders to retrieve.
required: true
schema:
type: string
- name: walletAddress
in: query
description: >-
The wallet address supposedly associated with the order. This is
used as a security measure preventing random order browsing.
required: true
schema:
type: string
- name: start
in: query
required: true
description: >-
The start date of the dataset. This is inclusive\: orders created at
this exact date should be included.
schema:
type: string
format: date
- name: end
in: query
required: true
description: >-
The end date of the dataset. This is inclusive\: orders created at
this exact date should be included.
schema:
type: string
format: date
- name: skip
in: query
required: true
description: The number of orders to skip in the dataset.
schema:
type: integer
- name: limit
in: query
required: true
description: >-
The maximum number of orders of the dataset to include in the
response.
schema:
type: integer
responses:
'200':
description: The widget is directly rendered by the endpoint
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/order'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/bad-request'
'403':
description: The API Key does not exist or doesn't allow access to this endpoint.
/sell-orders/{orderId}:
get:
tags:
- Orders
summary: Retrieves the status of a single off-ramp order
operationId: getOrder
security:
- {}
- oauth: []
- api_key: []
parameters:
- name: orderId
in: path
description: >-
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.
required: true
schema:
type: string
- name: walletAddress
in: query
description: >-
The wallet address supposedly associated with the order. This is
used as a security measure preventing random order browsing.
required: true
schema:
type: string
responses:
'200':
description: The widget is directly rendered by the endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/sell-order'
'404':
description: >-
The order doesn't exist or is not associated to the right wallet
address.
content: {}
/orders:
get:
tags:
- Orders
summary: Securely retrieves a list of orders
description: >-
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`.
operationId: getAllOrders
security:
- {}
- oauth: []
- api_key: []
parameters:
- name: start
in: query
required: true
description: >-
The start date of the dataset. This is inclusive\: orders created at
this exact date should be included.
schema:
type: string
format: date
- name: end
in: query
required: true
description: >-
The end date of the dataset. This is inclusive\: orders created at
this exact date should be included.
schema:
type: string
format: date
- name: skip
in: query
required: true
description: The number of orders to skip in the dataset.
schema:
type: integer
- name: limit
in: query
required: true
description: >-
The maximum number of orders of the dataset to include in the
response.
schema:
type: integer
responses:
'200':
description: The widget is directly rendered by the endpoint
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/order'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/bad-request'
'403':
description: The API Key does not exist or doesn't allow access to this endpoint.
/sell-orders:
get:
tags:
- Orders
summary: Securely retrieves a list of off-ramp orders
description: >-
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`.
operationId: getAllSellOrders
security:
- {}
- oauth: []
- api_key: []
parameters:
- name: start
in: query
required: true
description: >-
The start date of the dataset. This is inclusive\: orders created at
this exact date should be included.
schema:
type: string
format: date
- name: end
in: query
required: true
description: >-
The end date of the dataset. This is inclusive\: orders created at
this exact date should be included.
schema:
type: string
format: date
- name: skip
in: query
required: true
description: The number of orders to skip in the dataset.
schema:
type: integer
- name: limit
in: query
required: true
description: >-
The maximum number of orders of the dataset to include in the
response.
schema:
type: integer
responses:
'200':
description: The widget is directly rendered by the endpoint
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/sell-order'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/bad-request'
'403':
description: The API Key does not exist or doesn't allow access to this endpoint.
/verify/ip:
post:
tags:
- Utility Endpoints (For Consumption Only)
summary: Verify widget user
description: >-
Verify that the hash passed in the /buy and /sell calls matches the user
on the provider widget.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ipAddress:
type: string
format: ipv4
example: 192.168.1.1
hash:
type: string
example: 5d41402abc4b2a76b9719d911017c592
required:
- ipAddress
- hash
responses:
'200':
description: Verification result
content:
application/json:
schema:
type: boolean
example: true
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid input
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Internal server error
components:
schemas:
configuration:
type: object
required:
- version
properties:
version:
type: string
description: >-
The version of this document. This field is required by the backend
and is used to regenerate cached provider configurations.
updatedAt:
type: string
format: date-time
description: >-
The last time the configuration was updated. At the moment, this
information is not used by our back-end, so it is only informative
and may be used for troubleshooting. If a static file is served, use
the date at which it was last updated. If this endpoint is dynamic,
the last deployment date can be used.
features:
type: object
properties:
quotes:
type: object
properties:
enabled:
type: boolean
description: >-
If disabled, the provider won't appear in the quotes screen.
This needs to be agreed with the MetaMask On-Ramp team.
buy:
type: object
properties:
enabled:
type: boolean
authentication:
type: object
properties:
scheme:
type: string
enum:
- NONE
- OAUTH
- API-KEY
oauth:
type: object
properties:
audience:
type: string
description: The OAuth audience access tokens need to match
api_key:
type: object
properties:
locationType:
type: string
enum:
- HEADER
description: >-
The location of the API Key. Only HTTP header are
supported at the moment.
location:
type: string
description: The name of the header containing the API Key.
recurring:
type: object
description: >-
A structure defining the recurring payment feature. If
omitted, the provider only supports one-time payments.
properties:
enabled:
type: boolean
description: >-
If true, the provider supports recurring payments. If
false, the provider only supports one-time payments.
frequencies:
type: array
description: >-
The list of frequencies supported by the provider. If
the provider supports recurring payments, this list
should contain at least one frequency. Can be omitted if
the provider only supports one-time payments.
items:
$ref: '#/components/schemas/frequency'
redirectOrderId:
type: array
description: >-
After the buy flow has been performed in the provider
widget, the user is redirected to the "redirectUrl"
initially provided to the widget. An order Id parameter is
appended to this redirection URL so the order status can be
tracked. This parameter name is specified here. Multiple
parameter names can be provided, and the first matching one
will be used.
items:
type: string
orderCustomId:
type: boolean
description: >-
If true, MetaMask On-Ramp may provide an order custom ID
when displaying the buy widget. This custom ID will be used
to retrieve order status and details if an order is placed
by the user later
browser:
type: string
enum:
- APP_BROWSER
- IN_APP_OS_BROWSER
description: >-
APP_BROWSER displays the buy screen in a dedicated browser
isolated from any other browsers installed on the mobile
phone. IN_APP_OS_BROWSER uses the Operating System browser
inside the mobile app. It can reuse existing cookies and
user sessions.
userAgent:
type: string
description: >-
If not empty, this value will be used in API calls as the
HTTP header "User-Agent".
orderTracking:
type: object
properties:
enabled:
type: boolean
description: >-
If enabled, the MetaMask On-Ramp aggregator will track orders.
If disabled, users can still buy crypto currencies, but they
will only see blockchain transactions in MetaMask. These
transactions won't display any purchase details like the paid
fiat currency amount.
orderAnalytics:
type: object
properties:
enabled:
type: boolean
description: >-
If enabled, the MetaMask On-Ramp aggregator back end will use
the /orders endpoint to retrieve list of orders details.
description: >-
A list of features specific to MetaMask On-Ramp the provider
supports.
countries:
type: array
items:
type: object
properties:
id:
type: string
description: ISO 3166 Alpha-2 code of the supported country
states:
type: array
items:
type: string
description: ISO 3166-2 code of the supported state
unsupported:
type: array
items:
$ref: '#/components/schemas/unsupported'
description: The list of countries and states the provider supports.
payments:
type: array
items:
type: object
properties:
id:
type: string
enum:
- debit-credit-card
- apple-pay
- sepa-bank-transfer
- gbp-bank-transfer
- ach-bank-transfer
- instant-bank-transfer
- upi
- pix
description: >-
New payment methods need to be implemented in the MetaMask
On-Ramp back-end before they can be used by a provider. If
some of your payment methods are not present here, please
contact us and we'll do our best to integrate it.
unsupported:
type: array
items:
$ref: '#/components/schemas/unsupported'
description: The list of payment methods the provider supports.
fiat:
type: array
items:
type: object
properties:
id:
type: string
description: ISO 4217 code of the supported currency
paymentLimits:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The ID of a payment method defined in the "payments"
property
min:
type: string
max:
type: string
description: >-
The minimum and maximum amounts of fiat valid for this fiat
currency and payment method. Use quoted float numbers for
`min` and `max` (ex: "1.20") Cryptocurrency limits are
optional: if they are missing, fiat currency limits are used.
unsupported:
type: array
items:
$ref: '#/components/schemas/unsupported'
description: The list of fiat currencies the provider supports.
crypto:
type: array
items:
type: object
properties:
id:
type: string
description: >-
A provider-specific id of the crypto currency. It just needs
to be unique for each crypto currency. A crypto currency
available on multiple networks must be declared once for each
network. IDs can be prefixed by the network name, for example:
"ETH-Mainnet" and "ETH-Arbitrum". The ID won't be shown to the
user and is mainly used for referencing this crypto in your
endpoints.
address:
type: string
description: >-
For EVM currencies only. The smart contract address for this
crypto currency. If it is a native token (ex: ETH on mainnet),
use "0x0000000000000000000000000000000000000000".
network:
type: string
description: >-
The network ID (or chain ID) of the blockchain network. (ex:
"1" for ethereum mainnet). In the case of non-EVM you can
reference our list of networks in concepts -> Non EVM Chain
Support
assetId:
type: string
description: >-
For Non-EVM currencies only. Asset Ids can be referenced in
concepts -> Non EVM Chain Support
paymentLimits:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The ID of a payment method defined in the "payments"
property
min:
type: string
max:
type: string
description: >-
The minimum and maximum amounts of fiat valid for this fiat
currency and payment method. Use quoted float numbers for
`min` and `max` (ex: "1.20") Cryptocurrency limits are
optional: if they are missing, fiat currency limits are
used.
payoutLimits:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The ID of a payment method defined in the "payments"
property
min:
type: string
max:
type: string
description: >-
The minimum and maximum amounts of crypto valid for these
crypto currency and payment method. Use quoted float numbers
for `min` and `max` (ex: "1.20")
unsupported:
type: array
items:
$ref: '#/components/schemas/unsupported'
description: The list of crypto currencies the provider supports.
example:
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
frequency:
type: string
description: The frequency of a quote or an order.
enum:
- weekly
- monthly
unsupported:
type: object
properties:
region:
type: string
payment:
type: string
fiat:
type: string
crypto:
type: string
feature:
type: string
enum:
- buy
- buy-recurring
- sell
bad-request:
type: object
properties:
error:
type: string
description: >-
An message describing the error. It must include the invalid
parameters
example:
error: The XYZ field has an invalid format
order:
type: object
properties:
id:
type: string
customId:
type: string
description: >-
If the "order custom ID" is enabled in the /configuration endpoint,
an ID provided by MetaMask allowing to retrieve the order.
userId:
type: string
description: >-
An identifier that is the same for all orders of the same user. No
personally identifiable information is required, the ID doesn't need
to be a username or an email.
link:
type: string
description: >-
An URI pointing to a Provider webpage displaying the order details.
This webpage may require the user to login.
format: uri
crypto:
type: object
properties:
id:
type: string
address:
type: string
network:
type: string
fiatAmountInUsd:
type: string
description: >-
The equivalent of the fiatAmountIn field, converted to USD, using
the exchange rate at the time of the transaction. Use a quoted float
number (ex: "1.20")
fiat:
type: string
description: The ISO 4217 code of the fiat currency
payment:
type: string
description: The payment method used to buy
providerPayment:
type: string
description: >-
A provider-defined payment method, providing more details than the
payment field. For example, if a VISA credit card was used with with
the "debit-credit-card" payment method, this field may contain
"VISA".
cryptoAmountOut:
type: string
description: >-
The amount of crypto actually sent to the user wallet address. Use a
quoted float number (ex: "1.20")
region:
type: string
description: >-
The region of the user. Can be a country ID (ex: "us") or state ID
(ex: "us-al")
fiatAmountIn:
type: string
description: >-
The amount of fiat actually spent by the user (including fees.) Use
a quoted float number (ex: "1.20")
cryptoAmountIn:
type: string
description: >-
The amount of crypto actually sent to the provider wallet address.
Use a quoted float number (ex: "1.20")
fiatAmountOut:
type: string
description: >-
The amount of fiat actually sent to the user. Use a quoted float
number (ex: "1.20")
exchangeRate:
type: string
description: >-
The exchange rate used to get the amount of crypto. Use a quoted
float number (ex: "1.20")
processingFees:
type: array
items:
type: object
properties:
label:
type: string
fiatAmount:
type: string
description: >-
Amount of the fee taken by the provider, as an amount of the
order fiat currency (this field is required and must be
expressed in the order fiat currency.) Use a quoted float
number (ex: "1.20")
description: The list of fees associated to this order
networkFees:
type: array
items:
type: object
properties:
label:
type: string
fiatAmount:
type: string
description: >-
Amount of the fee taken by the network, as an amount of the
order fiat currency (this field is required and must be
expressed in the order fiat currency.) Use a quoted float
number (ex: "1.20")
description: The list of fees associated to this order
partnerFees:
type: array
items:
type: object
properties:
label:
type: string
fiatAmount:
type: string
description: >-
Amount of the fee taken by MetaMask, as an amount of the order
fiat currency (this field must be expressed in the order fiat
currency.) Use a quoted float number (ex: "1.20") If the
partner fee cannot be isolated from the provider fee
(`processingFees`), set `partnerFees` amount to `0`.
description: The list of fees associated to this order
createdAt:
type: string
description: The time the order has been registered in the Provider system
format: date-time
updatedAt:
type: string
description: The last time the order has been updated in the Provider system
format: date-time
transactionHash:
type: string
description: >-
The hash of the transaction transfering the crypto to the user
wallet. Depending on the provider behavior, transfers could be
bundled and a single transaction could be linked to multiple orders.
walletAddress:
type: string
description: >-
The wallet address of the user. When the order is completed, crypto
funds are sent to this address.
status:
type: string
enum:
- PENDING
- COMPLETED
- FAILED
- CANCELLED
description: >-
The status of the order. Pending orders are periodically polled by
MetaMask. Completed, failed or cancelled orders are never polled
again once MetaMask detects one of these statuses.
statusCode:
type: string
description: >-
If applicable, a code defined by the provider, providing more
details than the MetaMask-defined status field.
statusReason:
type: string
description: >-
If applicable, information explaining how the order has its current
status.
partnerAccountId:
type: string
description: >-
An value identifying Consensys/MetaMask as the partner associated
with the transaction
orderType:
type: string
enum:
- BUY
- TRANSFER
- SELL
recurring:
type: object
properties:
enabled:
type: boolean
description: >-
If true, the order is a recurring order. Recurring orders are
automatically created by MetaMask when the user has a recurring
transaction set up in the MetaMask UI.
isActive:
type: boolean
description: >-
If true, recurring orders are still expected to be generated
automatically by the provider. If false, recurring orders are
not expected to be created anymore, and aren't expected be
queried through this API.
frequency:
$ref: '#/components/schemas/frequency'
firstOrder:
type: string
description: >-
If the order is recurring, the ID of the first order of the
recurring purchase.
example:
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
sell-order:
type: object
properties:
id:
type: string
userId:
type: string
description: >-
An identifier that is the same for all orders of the same user. No
personally identifiable information is required, the ID doesn't need
to be a username or an email.
link:
type: string
description: >-
An URI pointing to a Provider webpage displaying the order details.
This webpage may require the user to login.
format: uri
crypto:
type: object
properties:
id:
type: string
address:
type: string
network:
type: string
fiatAmountOutUsd:
type: string
description: >-
The equivalent of the fiatAmountOut field, converted to USD, using
the exchange rate at the time of the transaction. Use a quoted float
number (ex: "1.20")
fiat:
type: string
description: The ISO 4217 code of the fiat currency
payment:
type: string
description: The payment method used to buy
providerPayment:
type: string
description: >-
A provider-defined payment method, providing more details than the
payment field. For example, if a VISA credit card was used with with
the "debit-credit-card" payment method, this field may contain
"VISA".
cryptoAmountIn:
type: string
description: >-
The amount of crypto sent or to be sent by the user. Use a quoted
float number (ex: "1.20")
region:
type: string
description: >-
The region of the user. Can be a country ID (ex: "us") or state ID
(ex: "us-al")
fiatAmountOut:
type: string
description: >-
The amount of fiat actually sent to the user fiat account. Use a
quoted float number (ex: "1.20")
exchangeRate:
type: string
description: >-
The exchange rate used to get the amount of fiat. Use a quoted float
number (ex: "1.20")
processingFees:
type: array
items:
type: object
properties:
label:
type: string
fiatAmount:
type: string
description: >-
Amount of the fee taken by the provider, as an amount of the
order fiat currency (this field is required and must be
expressed in the order fiat currency.) Use a quoted float
number (ex: "1.20")
description: The list of fees associated to this order
partnerFees:
type: array
items:
type: object
properties:
label:
type: string
fiatAmount:
type: string
description: >-
Amount of the fee taken by MetaMask, as an amount of the order
fiat currency (this field must be expressed in the order fiat
currency.) Use a quoted float number (ex: "1.20") If the
partner fee cannot be isolated from the provider fee
(`processingFees`), set `partnerFees` amount to `0`.
description: The list of fees associated to this order
createdAt:
type: string
description: The time the order has been registered in the Provider system
format: date-time
updatedAt:
type: string
description: The last time the order has been updated in the Provider system
format: date-time
transactionHash:
type: string
description: >-
The hash of the transaction transfering the crypto to the provider
wallet. This transaction is initiated by the user.
walletAddress:
type: string
description: The wallet address of the user, used to send crypto to the provider.
providerWalletAddress:
type: string
description: The wallet address of the provider, where the crypto must be sent.
status:
type: string
enum:
- CREATED
- INITIATED
- PENDING
- COMPLETED
- FAILED
- CANCELLED
description: >-
The status of the order. Initiated orders are polled by MetaMask
after the widget redirection and before asking the user to confirm
sending the funds. Pending orders are periodically polled by
MetaMask. Completed, failed or cancelled orders are never polled
again once MetaMask detects one of these statuses.
statusCode:
type: string
description: >-
If applicable, a code defined by the provider, providing more
details than the MetaMask-defined status field.
statusReason:
type: string
description: >-
If applicable, information explaining how the order has its current
status.
partnerAccountId:
type: string
description: >-
An value identifying Consensys/MetaMask as the partner associated
with the transaction
example:
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
securitySchemes:
api_key:
type: apiKey
name: api_key
in: header
oauth:
type: oauth2
description: >-
This API uses OAuth 2 with the Client Credentials grant flow. [More
info](https://api.example.com/docs/auth)
flows:
clientCredentials:
scopes:
example_scope: Scopes are defined by the provider
tokenUrl: https://www.crypto-provider-example.com/oauth/token