Quickstart

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 (see The Bridge app):

A sandbox API key

It starts with bridge_sbx_. See Create API keys.

Your server's IP address on the allowlist

Requests from addresses that are not on the list are blocked. See Allowlist your IP addresses.

Your API version

Find it in Settings → Integration or Settings → Account. Today it is 2026-10-29-atlas. See API versions.

Every request sends the same headers:

X-BRIDGE-API-Key: bridge_sbx_your_key_here
API-Version: 2026-10-29-atlas
Content-Type: application/json

Step 1: Add your customer

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.

{
  "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.

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"
  }'

{
  "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"
  }
}

A quote only lasts a short time (see Time limits). Create the payment straight away. If it expires, refresh it or get a new one.

Step 3: Create the payment

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

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.

{
  "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"
    }
  }
}

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, you’ll receive an event at each step:

payment.onramp.quote_locked
payment.onramp.fiat_pending
payment.onramp.fiat_received
payment.onramp.processing
payment.onramp.completed

Step 5: Check the result

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"

{
  "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.

You’ve made your first payment.

Next steps

Onramp in depth

Every state, every error, and what to do.

Webhooks

Get told the moment a payment changes.

Get started

Set up your account

Before you build

Core flows

Webhooks

Errors

Before you start

Step 1: Add your customer

Step 2: Get a quote

Step 3: Create the payment

Step 4: Watch the payment move

Step 5: Check the result

Next steps

Onramp in depth

Webhooks

​Before you start

​Step 1: Add your customer

​Step 2: Get a quote

​Step 3: Create the payment

​Step 4: Watch the payment move

​Step 5: Check the result

​Next steps

Onramp in depth

Webhooks

Before you start

Step 1: Add your customer

Step 2: Get a quote

Step 3: Create the payment

Step 4: Watch the payment move

Step 5: Check the result

Next steps