> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bridge.linkio.world/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Begin with a guide on the fastest path to a successful outcome.

> In this guide you'll make a test onramp in the `sandbox`: a customer pays ₦150,000 and receives USDC. No real money moves.

## Before you start

You need three things from the [sandbox Bridge app](https://sandbox.bridge.linkio.world) (see [The Bridge app](https://docs.bridge.linkio.world/control-app/overview.md)):

**1. A sandbox API key**

It starts with `bridge_sbx_`. See [Create API keys](https://docs.bridge.linkio.world/control-app/api-keys.md).

**2. Your server's IP address on the allowlist**

Requests from addresses that are not on the list are blocked. See [Allowlist your IP addresses](https://docs.bridge.linkio.world/control-app/ip-allowlist.md).

**3. Your API version**

Find it in **Settings → Integration** or **Settings → Account**. Today it is `2026-10-29-atlas`. See [API versions](https://docs.bridge.linkio.world/before-you-build/api-versions.md).

Every request sends the same headers:

```bash theme={null}
X-BRIDGE-API-Key: bridge_sbx_your_key_here
API-Version: 2026-10-29-atlas
Content-Type: application/json
```

## Step 1: Add your customer

```bash theme={null}
curl -X POST https://sandbox.core.linkio.world/api/customers/onboard \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "retail",
    "details": {
      "first_name": "Ada",
      "last_name": "Obi",
      "email": "ada@example.com",
      "phone": "+2348012345678"
    }
  }'
```

You get back the customer. Save the `id`.

```json theme={null}
{
  "id": "cus_4hT9pL2mQx8VnR3tY7wZ1cB5dE",
  "type": "retail",
  "name": "Ada Obi",
  "email": "ada@example.com",
  "phone": "+2348012345678",
  "address": null,
  "country": null,
  "metadata": {}
}
```

## Step 2: Get a quote

Ask how much USDC ₦150,000 buys. The USDC goes out on the Base network.

```bash theme={null}
curl -X POST https://sandbox.core.linkio.world/api/quotes/generate \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_4hT9pL2mQx8VnR3tY7wZ1cB5dE",
    "transaction_type": "onramp",
    "source_amount": "150000",
    "source_currency": "NGN",
    "target_currency": "USDC",
    "payment_method": "bank_transfer",
    "network": "base"
  }'
```

```json theme={null}
{
  "status": "success",
  "message": "Quote generated",
  "quote": {
    "id": "qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ",
    "source_amount": "150000",
    "source_currency": "NGN",
    "target_amount": "97.71",
    "target_currency": "USDC",
    "payment_method": "bank_transfer",
    "payout_method": "stablecoin",
    "network": "base",
    "transaction_type": "onramp",
    "rate": "1535",
    "expires_at": "2026-10-28T10:15:20.000Z"
  }
}
```

> [!WARNING]
>
> A quote only lasts a short time (see [Time limits](https://docs.bridge.linkio.world/before-you-build/time-limits.md)). Create the payment straight away. If it expires, [refresh it](https://docs.bridge.linkio.world/api-reference/quotes/refresh.md) or get a new one.

## Step 3: Create the payment

Use the quote and tell us which wallet should receive the USDC.

```bash theme={null}
curl -X POST https://sandbox.core.linkio.world/api/payments/onramp \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "customer_id": "cus_4hT9pL2mQx8VnR3tY7wZ1cB5dE",
    "quote_id": "qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ",
    "payment_details": {
      "type": "stablecoin",
      "currency": "USDC",
      "details": {
        "address": "0xaFB11F991f9c7DDB62463e4E16e917d6f92e9337",
        "network": "base"
      }
    }
  }'
```

You get back the payment and the **deposit instructions**: the bank account your customer must pay into.

```json theme={null}
{
  "status": "success",
  "message": "Onramp payment initiated",
  "payment": {
    "id": "pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
    "status": "pending",
    "state": "initiated",
    "event_id": "evt_2cB6dE8fK2mQ9xLp3VnR7tY1wZ",
    "deposit": {
      "type": "bank_transfer",
      "currency": "NGN",
      "details": {
        "account_name": "Bridge - Ada Obi",
        "account_number": "9912345678",
        "bank_name": "Example Bank"
      },
      "amount": "150000",
      "amount_expected": "150050.20"
    }
  }
}
```

> [!NOTE]
>
> Show your customer the bank details and the **`amount_expected`**. That is the exact amount they must send. Paying more or less can stop the payment.

## Step 4: Watch the payment move

In the sandbox, the payment moves through each step by itself, about every 3 seconds. If you added a [webhook](https://docs.bridge.linkio.world/control-app/webhooks.md), you'll receive an event at each step:

```text theme={null}
payment.onramp.quote_locked
payment.onramp.fiat_pending
payment.onramp.fiat_received
payment.onramp.processing
payment.onramp.completed
```

## Step 5: Check the result

```bash theme={null}
curl https://sandbox.core.linkio.world/api/payments/pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE/details \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas"
```

```json theme={null}
{
  "status": "success",
  "message": "Payment retrieved",
  "payment": {
    "id": "pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
    "customer_id": "cus_4hT9pL2mQx8VnR3tY7wZ1cB5dE",
    "reference_id": "ref_7tY1wZ4cB6dE8fK2mQ9xLp3VnR",
    "quote_id": "qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ",
    "type": "onramp",
    "status": "success",
    "state": "completed",
    "transaction_hash": "0x6c11…",
    "created_at": "2026-10-28T10:15:02.000Z",
    "updated_at": "2026-10-28T10:15:17.000Z"
  }
}
```

`status: success` and `state: completed` mean the USDC has been sent to the wallet. `transaction_hash` is the blockchain transaction ID, so your customer can look it up.

> [!TIP]
>
> You've made your first payment.

## Next steps

> [card] [Onramp in depth](https://docs.bridge.linkio.world/flows/onramp.md)
>
> Every state, every error, and what to do.

> [card] [Webhooks](https://docs.bridge.linkio.world/webhooks/overview.md)
>
> Get told the moment a payment changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.