Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt

Use this file to discover all available pages before exploring further.

The Buy frame is a headless frame. It evaluates transaction requirements, creates the transaction, and completes post-transaction processing — all without rendering any UI. Your confirmation screen, loading states, and purchase button remain fully under your control.

​
URL

https://blocks.moonpay.com/platform/v1/buy

​
Requirements

​
Size

The frame is headless. Mount it with zero dimensions so it does not affect your layout:
Example
<iframe
  src="https://blocks.moonpay.com/platform/v1/buy?..."
  style="position: absolute; width: 0; height: 0; border: none; overflow: hidden;"
/>

​
Initialization parameters

PropertyTypeRequiredDescription
clientTokenstring✅The client token returned from the connect flow.
channelIdstring✅A unique identifier for the frame generated on your client. This value is attached to each postMessage payload to help identify messages.

The format of this string is up to you.
signaturestring✅The quote signature from the quote endpoint. Pass signature as returned.
externalTransactionIdstringYour own identifier for the transaction. Stored and associated with the MoonPay transaction for correlation.

​
Events

All events are dispatched using the message pattern described in the frames protocol. Below are the event payloads specific to the Buy frame.

​
Outbound events

frame->parent These events are sent from this frame to the parent window.

​
handshake

The frame requests that you open a message channel. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "handshake"
}

​
ready

The buy pipeline is starting. Use this to show a loading indicator in your UI. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ready"
}

​
complete

The transaction is complete. Use the transaction ID to track final status via polling. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "transaction": {
      "id": "txn_01",
      "status": "pending"
    }
  }
}

​
challenge

Verification is required before the transaction can proceed. Render the challenge frame at the provided URL. Do not construct the URL yourself — use it as-is. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "challenge",
  "payload": {
    "kind": "frame",
    "url": "https://blocks.moonpay.com/platform/v1/challenge?challengeToken=..."
  }
}

​
error

A terminal error occurred. Remove the frame and surface the message to the developer. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "error",
  "payload": {
    "code": "invalidQuote",
    "message": "Unable to decode the quote signature."
  }
}
CodeDescription
configurationErrorMissing or invalid signature parameter
invalidQuoteUnable to decode the quote signature
genericUnspecified error

​
Inbound events

parent->frame These events are sent from the parent window to this frame.

​
ack

Acknowledge the handshake. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ack"
}

​
setQuote

Provide a new quote to the frame. Send this when the current quote expires before the customer completes the purchase. Pass signature as returned by the quote endpoint. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "setQuote",
  "payload": {
    "quote": {
      "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}