> ## Documentation Index > Fetch the complete documentation index at: https://docs.meld.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a crypto widget > Use this endpoint to create a crypto widget for a session to buy or sell crypto. ## OpenAPI ````yaml /openapi/crypto-20260203.json post /crypto/session/widget openapi: 3.1.0 info: title: CRYPTO termsOfService: urn:tos license: name: Apache 2.0 url: https://springdoc.org version: '2026-02-03' description: '' servers: - url: https://api-sb.meld.io description: Meld API sandbox - url: https://api.meld.io description: Meld API production security: [] tags: - name: Retail Ramp description: '' - name: Headless description: '' - name: Payment description: '' - name: Session description: '' paths: /crypto/session/widget: post: tags: - Retail Ramp summary: Create a crypto widget description: >- Use this endpoint to create a crypto widget for a session to buy or sell crypto. operationId: /crypto-session-widget-create requestBody: content: application/json: schema: $ref: '#/components/schemas/SessionTokenForWidgetRequestV20231219' example: sessionType: BUY sessionData: serviceProvider: TOPPER countryCode: US sourceCurrencyCode: USD sourceAmount: '100' destinationCurrencyCode: BTC walletAddress: bc1qr74wmrcwqq9w5yxczxj6udts9mnqsh3xlhk5yp externalSessionId: example-session-id externalCustomerId: example-customer-id required: true responses: '200': description: Widget created content: '*/*': schema: $ref: '#/components/schemas/SessionTokenResponse' '400': description: 'Bad Request : check request values and format' '401': description: Invalid credentials '403': description: Unauthenticated or authenticated with insufficient access '500': description: >- Server Error. This applies to all 5xx errors, including but not limited to 500, 501, 502, 503, and 504 errors. You should treat all of these errors the same. security: - ApiKeyAuth: [] components: schemas: SessionTokenForWidgetRequestV20231219: type: object properties: bypassKyc: type: boolean default: false description: >- When true, the system will automatically look up the customer's KYC status and generate a share token if KYC is approved. Requires a valid customerId or externalCustomerId. customerId: type: string description: >- Meld generated unique identifier for your customer. This should be used to track customer activity. externalCustomerId: type: string description: >- Your unique identifier for your customer. If maintaining your own customer management system this can also be used for tracking customer activity. externalSessionId: type: string description: >- Your reference id for your widget session, if you use this optional field you must pass in a unique value each time externalSubaccountCustomerId: type: string description: >- Optional external identifier for the sub-account customer this transaction belongs to. Used for tracking when multiple businesses operate under one Meld account. A sub-account customer must be created first before it can be referenced. sessionData: description: Data related to the session allOf: - $ref: '#/components/schemas/SessionDataInputV20231219' sessionType: type: string description: The type of widget session to create enum: - BUY - SELL - TRANSFER subaccountCustomerId: type: string description: >- Optional Meld customer id used to track the business sub-account this transaction belongs to when multiple businesses operate under one Meld account. required: - sessionData - sessionType SessionTokenResponse: type: object properties: customerId: type: string description: >- Meld generated unique identifier for your customer. This should be used to track customer activity. externalCustomerId: type: string description: >- Your unique identifier for your customer. If maintaining your own customer management system this can also be used for tracking customer activity. externalSessionId: type: string description: Your reference Id for your widget session id: type: string description: Unique identifier for this session serviceProviderWidgetUrl: type: string description: The service provider's widget URL token: type: string description: The session token widgetUrl: type: string description: The crypto widget URL SessionDataInputV20231219: type: object description: Data related to the session oneOf: - title: CryptoBuySessionData allOf: - $ref: '#/components/schemas/CryptoBuySessionData' - title: CryptoSellSessionData allOf: - $ref: '#/components/schemas/CryptoSellSessionData' - title: CryptoTransferSessionData allOf: - $ref: '#/components/schemas/CryptoTransferSessionData' properties: clientIpAddress: type: string description: The client's IP address kycInfo: description: >- Optional KYC information for token passthrough. When provided with a valid KYC token from a supported provider, the verification can be transferred to downstream providers that support it. allOf: - $ref: '#/components/schemas/KycInfo' lockFields: type: array description: >- Where supported by the Service Provider, Meld can help you lock the cryptocurrency and/or wallet address fields within the widget. Enable this by passing in the "destinationCurrencyCode" and/or "walletAddress" as strings in this field. See [this page](https://docs.meld.io/docs/white-label-cutomization#locking-fields) for more details. items: type: string enum: - cryptoCurrency - destinationCurrencyCode - sourceCurrencyCode - walletAddress - sourceAmount - paymentMethodType redirectUrl: type: string description: The url to redirect to following completion of the widget flow serviceProvider: type: string description: >- The service provider used for this transaction Reference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers enum: - ALCHEMYPAY - BANXA - BILIRA - BINANCECONNECT - BINANCEPAY - BLOCKCHAINDOTCOM - BOOMFI - BTCDIRECT - COINBASEPAY - FONBNK - GUARDARIAN - KRYPTONIM - KOYWE - MESH - MERCURYO - MESO - ONMETA - ONRAMPMONEY - PAYBIS - PAYPAL - RAMP - REVOLUT - ROBINHOOD - SARDINE - SHIFT4 - SIMPLEX - SKRILLCRYPTO - STRIPE - SWAPPED - TOPPER - TRANSAK - TRANSFI - UNLIMIT - YELLOWCARD walletTag: type: string description: >- Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies. required: - serviceProvider CryptoBuySessionData: type: object properties: clientIpAddress: type: string description: The client's IP address countryCode: type: string description: Two-letter country code (ISO 3166-1 alpha-2) default: US destinationCurrencyCode: type: string description: The cryptocurrency the customer is buying (e.g. BTC, ETH). minLength: 1 default: BTC institutionId: type: string description: >- If provided, the institution to bypass the institution selection screen in the service provider's widget. Currently this is only supported for MESH widget sessions. kycInfo: description: >- Optional KYC information for token passthrough. When provided with a valid KYC token from a supported provider, the verification can be transferred to downstream providers that support it. allOf: - $ref: '#/components/schemas/KycInfo' lockFields: type: array description: >- Where supported by the Service Provider, Meld can help you lock the cryptocurrency and/or wallet address fields within the widget. Enable this by passing in the "destinationCurrencyCode" and/or "walletAddress" as strings in this field. See [this page](https://docs.meld.io/docs/white-label-cutomization#locking-fields) for more details. items: type: string enum: - cryptoCurrency - destinationCurrencyCode - sourceCurrencyCode - walletAddress - sourceAmount - paymentMethodType paymentMethodType: type: string description: >- Payment Method Type The paymentMethodType and paymentMethodSubType included here are a sample set. Review the [Supported Payment Methods](https://www.meld.io/coverage/payment-methods) section to view the complete list. redirectUrl: type: string description: The url to redirect to following completion of the widget flow refundWalletAddress: type: string description: >- Optional wallet address where the swap provider sends refunds if the swap fails. Only applicable for ramp+swap (e.g. fiat->USDC->USDH) sessions. serviceProvider: type: string description: >- The service provider used for this transaction Reference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers enum: - ACROSS - AEROPAY - AKOYA - ALCHEMYPAY - APPLEPAY - AUTHORIZENET - BANXA - BILIRA - BINANCECONNECT - BINANCEPAY - BLOCKCHAINDOTCOM - BOOMFI - BRAINTREE - BRALE - BTCDIRECT - CASHAPP - CHECKOUT - CIRCLE - COINBASEPAY - COINFLOW - DUENETWORK - ELDORADO - FINICITY - FLASHNET - FONBNK - GUARDARIAN - HARBOUR - KOYWE - KRYPTONIM - MERCURYO - MESH - MESO - MOONPAY - MOOV - MX - NMI - NOAH - ONMETA - ONRAMPMONEY - PAYBIS - PAYPAL - PLAID - RAMP - REVOLUT - ROBINHOOD - ROUTERPROTOCOL - SALTEDGE - SALTEDGEPARTNERS - SARDINE - SHIFT4 - SHOPIFY - SIMPLEX - SKRILLCRYPTO - SQUARE - STRIPE - SUMSUB - SWAPPED - TANGOCARD - TELLER - TOPPER - TRANSAK - TREMENDOUS - TRANSFI - UNLIMIT - UPHOLD - WYRE - XANPOOL - YELLOWCARD - YODLEE default: TRANSAK sourceAmount: type: string description: >- The amount of source currency your customer wants tosend in this transaction (e.g., 50.05) minLength: 1 default: '100' sourceCurrencyCode: type: string description: The fiat currency the user is buying crypto with (e.g. USD, EUR). minLength: 1 default: USD walletAddress: type: string description: Your customer's wallet address minLength: 1 default: 1EEo4ioA4spdJ2ZxiSQ1hWsp3Ve81ZRZ2F walletTag: type: string description: >- Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies. required: - countryCode - destinationCurrencyCode - serviceProvider - sourceAmount - sourceCurrencyCode - walletAddress title: Buy Crypto CryptoSellSessionData: type: object properties: clientIpAddress: type: string description: The client's IP address countryCode: type: string description: Two-letter country code (ISO 3166-1 alpha-2) minLength: 1 destinationCurrencyCode: type: string description: >- The fiat currency the customer is selling crypto for (e.g. USD, EUR). minLength: 1 kycInfo: description: >- Optional KYC information for token passthrough. When provided with a valid KYC token from a supported provider, the verification can be transferred to downstream providers that support it. allOf: - $ref: '#/components/schemas/KycInfo' lockFields: type: array description: >- Where supported by the Service Provider, Meld can help you lock the cryptocurrency and/or wallet address fields within the widget. Enable this by passing in the "destinationCurrencyCode" and/or "walletAddress" as strings in this field. See [this page](https://docs.meld.io/docs/white-label-cutomization#locking-fields) for more details. items: type: string enum: - cryptoCurrency - destinationCurrencyCode - sourceCurrencyCode - walletAddress - sourceAmount - paymentMethodType paymentMethodType: type: string description: >- Payment Method Type The paymentMethodType and paymentMethodSubType included here are a sample set. Review the [Supported Payment Methods](https://www.meld.io/coverage/payment-methods) section to view the complete list. redirectFlow: type: boolean default: false description: >- The user is redirected back to the wallet, and the wallet gets the amount, token, and wallet address to send money to from the SP’s API, then queues up a transfer in the wallet UI and the user just hits confirm redirectUrl: type: string description: The url to redirect to following completion of the widget flow refundWalletAddress: type: string description: >- Optional wallet address where the swap provider sends refunds if the swap fails. Only applicable for sell+swap (e.g. USDH->USDC->fiat) sessions. Defaults to walletAddress if not provided. serviceProvider: type: string description: >- The service provider used for this transaction Reference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers enum: - ACROSS - AEROPAY - AKOYA - ALCHEMYPAY - APPLEPAY - AUTHORIZENET - BANXA - BILIRA - BINANCECONNECT - BINANCEPAY - BLOCKCHAINDOTCOM - BOOMFI - BRAINTREE - BRALE - BTCDIRECT - CASHAPP - CHECKOUT - CIRCLE - COINBASEPAY - COINFLOW - DUENETWORK - ELDORADO - FINICITY - FLASHNET - FONBNK - GUARDARIAN - HARBOUR - KOYWE - KRYPTONIM - MERCURYO - MESH - MESO - MOONPAY - MOOV - MX - NMI - NOAH - ONMETA - ONRAMPMONEY - PAYBIS - PAYPAL - PLAID - RAMP - REVOLUT - ROBINHOOD - ROUTERPROTOCOL - SALTEDGE - SALTEDGEPARTNERS - SARDINE - SHIFT4 - SHOPIFY - SIMPLEX - SKRILLCRYPTO - SQUARE - STRIPE - SUMSUB - SWAPPED - TANGOCARD - TELLER - TOPPER - TRANSAK - TREMENDOUS - TRANSFI - UNLIMIT - UPHOLD - WYRE - XANPOOL - YELLOWCARD - YODLEE sourceAmount: type: string description: >- The amount of source currency your customer wants tosend in this transaction (e.g., 50.05) minLength: 1 sourceCurrencyCode: type: string description: The cryptocurrency the customer is selling (e.g. BTC, ETH). minLength: 1 walletAddress: type: string description: Your customer's wallet address. Not required for selling crypto. walletTag: type: string description: >- Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies. required: - countryCode - destinationCurrencyCode - serviceProvider - sourceAmount - sourceCurrencyCode title: Sell Crypto CryptoTransferSessionData: type: object properties: clientIpAddress: type: string description: The client's IP address countryCode: type: string description: Two-letter country code (ISO 3166-1 alpha-2) institutionId: type: string description: >- If provided, the institution to bypass the institution selection screen in the service provider's widget. Currently this is only supported for MESH widget sessions. kycInfo: description: >- Optional KYC information for token passthrough. When provided with a valid KYC token from a supported provider, the verification can be transferred to downstream providers that support it. allOf: - $ref: '#/components/schemas/KycInfo' lockFields: type: array description: >- Where supported by the Service Provider, Meld can help you lock the cryptocurrency and/or wallet address fields within the widget. Enable this by passing in the "destinationCurrencyCode" and/or "walletAddress" as strings in this field. See [this page](https://docs.meld.io/docs/white-label-cutomization#locking-fields) for more details. items: type: string enum: - cryptoCurrency - destinationCurrencyCode - sourceCurrencyCode - walletAddress - sourceAmount - paymentMethodType redirectUrl: type: string description: The url to redirect to following completion of the widget flow serviceProvider: type: string description: >- The service provider used for this transaction Reference [Crypto supported service providers](https://www.meld.io/coverage/service-providers) for a full list of supported service providers enum: - ACROSS - AEROPAY - AKOYA - ALCHEMYPAY - APPLEPAY - AUTHORIZENET - BANXA - BILIRA - BINANCECONNECT - BINANCEPAY - BLOCKCHAINDOTCOM - BOOMFI - BRAINTREE - BRALE - BTCDIRECT - CASHAPP - CHECKOUT - CIRCLE - COINBASEPAY - COINFLOW - DUENETWORK - ELDORADO - FINICITY - FLASHNET - FONBNK - GUARDARIAN - HARBOUR - KOYWE - KRYPTONIM - MERCURYO - MESH - MESO - MOONPAY - MOOV - MX - NMI - NOAH - ONMETA - ONRAMPMONEY - PAYBIS - PAYPAL - PLAID - RAMP - REVOLUT - ROBINHOOD - ROUTERPROTOCOL - SALTEDGE - SALTEDGEPARTNERS - SARDINE - SHIFT4 - SHOPIFY - SIMPLEX - SKRILLCRYPTO - SQUARE - STRIPE - SUMSUB - SWAPPED - TANGOCARD - TELLER - TOPPER - TRANSAK - TREMENDOUS - TRANSFI - UNLIMIT - UPHOLD - WYRE - XANPOOL - YELLOWCARD - YODLEE sourceAmount: type: string description: >- The amount of source currency your customer wants totransfer (e.g., 50.05). It only applies if one source currency code is passed in. sourceCurrencyCodes: type: array description: >- Allowable crypto currencies for the customer to transfer (e.g. BTC, ETH). If the currency to transfer is already known, then this list should be singular and the customer will not have the option to select a different crypto currency in the service provider's widget. Alternatively, if the currency to transfer is not yet known and it is desired that the customer select it themselves in the service provider widget, then this list will restrict which crypto currencies are made available. However, this latter option of passing in multiple currencies is only supported by select service providers (MESH, ROBINHOOD). At least one currency must be passed in. The accompanying sourceAmount field should only be present if a single crypto currency is passed in. items: type: string minItems: 1 uniqueItems: true walletAddress: type: string description: Your customer's wallet address walletTag: type: string description: >- Your customer's wallet tag/destination tag/memo. This field is required for certain cryptocurrencies. required: - countryCode - serviceProvider - sourceCurrencyCodes title: Transfer Crypto KycInfo: type: object description: KYC verification information for token passthrough properties: kycProvider: type: string description: The KYC provider that issued the token enum: - SUMSUB example: SUMSUB kycShareToken: type: string description: >- The shareable KYC token from the KYC provider (e.g., Sumsub share token). This token can be used to transfer verified KYC status to downstream providers. Required when kycProvider is specified. example: _act-sbx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization x-default: BASIC ````