> ## 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.

# Quick Start

This quick start gets developers integrating Meld crypto for the first time from zero to a working test transaction in under 30 minutes. Pick the Widget path for a no-code launch, or the White-Label API path if you plan to build your own UI.

<Note>
  **Sandbox base URL:** `https://api-sb.meld.io` — production credentials and URLs are separate. All examples below assume sandbox.
</Note>

## 🚀 Choose your path

### Widget Integration — 5 minutes

**Perfect for:** Fast launch, minimal development effort

* **What you get:** Ready-made UI, instant crypto functionality
* **What you do:** Get public-key URL → use directly → redirect users
* **Development required:** None

➡️ **[Jump to Widget Quick Start](#widget-integration-quick-start)**

### White-Label API — 30 minutes

**Perfect for:** Custom UI, complete design control

* **What you get:** API endpoints for quotes, transactions, webhooks
* **What you do:** Build custom UI → API integration → launch provider widgets
* **Development required:** API integration, custom UI

➡️ **[Jump to White-Label Quick Start](#white-label-api-quick-start)**

***

# Widget Integration Quick Start

**Time required:** 5 minutes
**Difficulty:** No coding required

## Before you begin

* A Meld dashboard invitation (check your email; if missing contact your account manager)
* Access to the Meld dashboard's **Developer** tab

## Step 1: Get your public-key URL

The Meld Dashboard provides a complete, ready-to-use Widget URL.

1. Check your email for the Meld dashboard invitation
2. Click the invitation link and log in
3. In the dashboard, navigate to the **Developer** tab
4. Find **Public Crypto Widget Key** — this is your complete URL
5. Copy and save your Public Key URL securely

<Note>
  You get a complete URL from the dashboard, not just a key. This URL is ready to use immediately.
</Note>

## Step 2: Use your Widget URL

Append optional query parameters to pre-fill or lock fields:

```
https://meldcrypto.com/?publicKey=your_public_key&sourceAmount=100&destinationCurrencyCode=BTC&countryCode=US
```

See the [URL Parameters Guide](/docs/stablecoins/meld-checkout-integration/meld-checkout-guide/url-parameters) for all available parameters and the [Customization Guide](/docs/stablecoins/meld-checkout-integration/meld-checkout-guide/meld-checkout-customization) for styling options.

### Integration examples

**HTML link:**

```html theme={null}
<a href="https://meldcrypto.com/?publicKey=your_public_key" target="_blank">
  Buy Crypto
</a>
```

**JavaScript redirect:**

```javascript theme={null}
function buyCrypto() {
  window.location.href = 'https://meldcrypto.com/?publicKey=your_public_key';
}
```

## Step 3: Test your integration

1. Use your sandbox Widget URL (from the Developer tab in the sandbox environment)
2. Open the URL in your browser
3. Complete a test transaction using the [test credentials](/docs/stablecoins/sandbox-guide/test)
4. Verify the result in the dashboard — check the **Transactions** tab

<Tip>
  If your transaction does not appear, open the **Status** dropdown on the Transactions tab and select **Select All** to include in-progress statuses.
</Tip>

## Step 4: Go live

1. Use your production Widget URL (from the Developer tab in the production environment)
2. Test with a small real transaction
3. Start directing users to your widget

✅ Widget integration complete. Users can now buy crypto directly through your application.

➡️ **[Meld Checkout Customization Guide](/docs/stablecoins/meld-checkout-integration/meld-checkout-guide/meld-checkout-customization)** — styling and advanced options

***

# White-Label API Quick Start

**Time required:** \~30 minutes
**Difficulty:** API knowledge required

## Before you begin

* A Meld dashboard invitation (check your email)
* Access to the **Developer → API Keys** section of the dashboard
* A publicly reachable URL if you want to receive webhooks (optional; you can also poll the API)

## Step 1: Get your API key

Your API key is required for all Meld API calls.

1. Check your email for the Meld dashboard invitation
2. Click the invitation link and log in
3. In the dashboard, navigate to **Developer → API Keys**
4. Click **Reveal Key**
5. Copy and save your API key securely

<Warning>
  Always prefix your API key with `BASIC ` in the `Authorization` header.

  Example: `Authorization: BASIC W9kZTT7332okCEc1A9aqAq:3sYKoXQv6oHVHSts7G2agw9vTCXz`
</Warning>

***

## Step 2: Set up webhooks (optional)

Webhooks notify your server when transactions are created and updated. You can complete this step later and poll the API instead.

### Requirements

* A publicly accessible URL (localhost will not work)
* For testing, consider [ngrok](https://ngrok.com/), [webhook.site](https://webhook.site/) or similar services

### Setup

1. Navigate to **Developer → Webhooks** in the dashboard
2. Click **Add Endpoint**
3. Enter your webhook URL (must start with `http` or `https`)
4. Give your webhook a descriptive name
5. Select **Subscribe to all events**
6. Click **Add endpoint**

<Note>
  You will receive notifications to this URL for all transaction creations and updates.
</Note>

***

## Step 3: Test your API connection

Verify your API key by requesting a price quote.

* **Endpoint:** `POST /payments/crypto/quote`
* **Authorization:** `BASIC [your-api-key]`

### Request

```json theme={null}
{
  "countryCode": "US",
  "sourceCurrencyCode": "USD",
  "destinationCurrencyCode": "BTC",
  "paymentMethodType": "CREDIT_DEBIT_CARD",
  "sourceAmount": 100
}
```

### Example response

```json theme={null}
{
  "quotes": [
    {
      "serviceProvider": "TRANSAK",
      "sourceAmount": 100,
      "sourceCurrencyCode": "USD",
      "destinationAmount": 0.00163,
      "destinationCurrencyCode": "BTC",
      "exchangeRate": 61349.69,
      "totalFee": 3.45
    }
  ]
}
```

### Testing options

* Use Meld's [Postman collection](https://www.postman.com/meldeng/workspace/meld-io-public-api-collection)
* Use the interactive docs in your dashboard

### Expected result

✅ `200 OK` with quote details. If you receive `401 Unauthorized`, recheck the `BASIC ` prefix and your key.

***

## Step 4: Create a test transaction

Create a test transaction without using real money.

* **Endpoint:** `POST /crypto/session/widget`
* **Authorization:** `BASIC [your-api-key]`

### Request

```json theme={null}
{
  "countryCode": "US",
  "sourceCurrencyCode": "USD",
  "destinationCurrencyCode": "BTC",
  "paymentMethodType": "CREDIT_DEBIT_CARD",
  "sourceAmount": 100,
  "serviceProvider": "TRANSAK",
  "walletAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
}
```

### Example response

```json theme={null}
{
  "id": "ses_01HEXAMPLEID",
  "widgetUrl": "https://global-stg.transak.com/?apiKey=...&sessionId=...",
  "token": "eyJhbGciOi..."
}
```

<Note>
  Replace `walletAddress` with your own test wallet or use the example above.
</Note>

### Complete the test flow

1. Copy the `widgetUrl` from the API response
2. Open the URL in your browser
3. For KYC testing, use any fake SSN and any image for the ID upload
4. For payment testing, use card `4111 1111 1111 1111`, any future expiry, and any 3-digit CVV

📚 **Full test data reference:** [Sandbox testing credentials](/docs/stablecoins/sandbox-guide/test)

***

## Step 5: Verify your transaction

### Option A — Using webhooks

1. Check your webhook endpoint for the transaction notification
2. Extract the `transactionId` from the webhook payload
3. Call `GET /payments/transactions/{transactionId}` to retrieve the full record

### Option B — Without webhooks

1. Call `GET /payments/transactions` to return your recent transactions
2. Locate your `transactionId` and read its current `status`

### Dashboard verification

1. Navigate to the **Transactions** tab
2. If your transaction isn't visible, click the **Status** dropdown and select **Select All**

✅ White-Label API integration complete. You can now build custom crypto experiences.

➡️ **[Build Custom UI Guide](/docs/stablecoins/white-label-api-integration/whitelabel-api-guide)** — complete implementation guide

***

## Troubleshooting

### 🚫 401 Unauthorized

* Ensure `BASIC ` is prefixed before your API key
* Check for extra spaces or incorrect formatting

### 🚫 Webhook not received

* Verify URL is publicly accessible
* Check firewall settings
* Ensure the webhook endpoint returns a `2xx` status code

### 🚫 Transaction not visible

* Change the status filter to **Select All** in the dashboard
* Wait 30 seconds and refresh
* Confirm you are looking at the correct environment (sandbox vs production)

<Tip>
  For a full list of transaction states and what each one means, see [Transaction Statuses](/docs/stablecoins/for-all-products/transaction-statuses).
</Tip>