Skip to main content

Order tracking

After displaying the provider buy widget to the user, MetaMask tracks the associated order.


If an order has been placed, the widget should only execute the redirection URL when the /orders/{orderId} endpoint is ready to return information. If a call to the endpoint says the order doesn't exist, MetaMask dismisses it and never shows it to the user. The provider is responsible for waiting for the endpoint readiness before performing the redirection. This redirection must happen automatically without requiring user action

If no order is placed, nothing happens and the user returns to MetaMask.

If an order is placed, MetaMask keeps refreshing its status and information until it reaches one of the following final states:

  • CREATED - Some user action is required to move this order forward such as sending crypto for an offramp.
  • COMPLETED - The purchase is successful.
  • FAILED - The purchase can't be finalized due to an error.
  • CANCELLED - The order is manually cancelled by the user or provider.

MetaMask keeps refreshing the order until it reaches a final state. The provider is responsible for detecting and handling orders stuck in a PENDING state. If the order is in the CREATED state polling will only occur when the user loads/refreshed the page/app.

MetaMask On-Ramp Order Tracking