Skip to main content
This guide walks through a complete ONRAMP flow: converting USD to USDC on Gnosis Chain.

​
Overview

1

Create Customer

Get access token for API calls
2

Get Indicative Quote

Compare pricing across providers
3

Get Requirements

Fetch field schemas for the currency pair
4

Create Intent

Submit the ONRAMP intent
5

Handle Compliance

Complete KYC if required
6

Execute Transaction

Trigger the transaction
7

Monitor & Complete

Track status until completion

​
Prerequisites

  • Gnosis Ramp API credentials (Getting Started)
  • A connected ramp provider that supports USD → USDC_GNO

​
Step 1: Create Customer

For faster compliance with KYC sharing, use external authentication instead.

​
API Call

POST /v1/customers

​
Sample Request Body

{
  "id": "user-12345"
}

​
Sample Response

{
  "id": "user-12345",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "createdAt": "2026-03-29T10:00:00.000Z",
  "updatedAt": "2026-03-29T10:00:00.000Z"
}

​
Step 2: Get Indicative Quote

Before creating an intent, fetch indicative quotes to show users pricing options.

​
API Call

GET /v1/intent/quote

​
Sample Request

GET /v1/intent/quote?srcCurrencyCode=USD&destCurrencyCode=USDC_GNO&srcAmount=100.00&countryCode=US

​
Sample Response

{
  "quotes": [
    {
      "providerId": "bridge",
      "type": "ONRAMP",
      "rail": "ACH",
      "hasIndicativePrice": true,
      "destAmount": "98.50",
      "exchangeRate": "0.9850",
      "fees": {
        "currencyCode": "USD",
        "totalFee": "1.50",
        "networkFee": "0.50",
        "processingFee": "0.75",
        "partnerFee": "0.25"
      }
    }
  ]
}
Quotes are non-binding estimates. The actual rate is determined at the time of settlement. See Getting a Quote for details.

​
Step 3: Get Requirements

​
API Call

GET /v1/intent/requirements

​
Sample Request

GET /v1/intent/requirements?srcCurrencyCode=USD&destCurrencyCode=USDC_GNO

​
Sample Response

{
  "src": {
    "currencyCode": "USD",
    "schema": {
      "type": "object",
      "required": ["countryCode", "currency", "rail"],
      "properties": {
        "countryCode": { "const": "US" },
        "currency": { "const": "USD" },
        "rail": { "type": "string", "enum": ["ACH", "WIRE"] }
      }
    }
  },
  "dest": {
    "currencyCode": "USDC_GNO",
    "schema": {
      "type": "object",
      "required": ["address", "currency"],
      "properties": {
        "address": { "pattern": "^0x[a-fA-F0-9]{40}$" },
        "currency": { "const": "USDC_GNO" }
      }
    }
  }
}
Use the schemas to build your form and validate input.

​
Step 4: Create Intent

​
API Call

POST /v1/intent

​
Sample Request Body

{
  "src": {
    "currencyCode": "USD",
    "details": {
      "countryCode": "US",
      "rail": "ACH"
    }
  },
  "dest": {
    "currencyCode": "USDC_GNO",
    "details": {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f..."
    }
  },
  "srcAmount": "100.00",
  "autoExecute": true,
  "onboardingRedirectUrl": "https://yourapp.com/ramp/callback"
}

​
Sample Response

{
  "intent": {
    "id": "int_abc123def456",
    "status": "CREATED",
    "type": "ONRAMP",
    "src": {
      "type": "BANK_ACCOUNT",
      "currency": "USD",
      "details": {
        "countryCode": "US",
        "rail": "ACH"
      }
    },
    "dest": {
      "type": "CRYPTO_ADDRESS",
      "currency": "USDC_GNO",
      "details": {
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f..."
      }
    },
    "srcAmount": "100.00",
    "provider": "bridge",
    "autoExecute": true
  },
  "onboardingUrl": "https://onboarding.ramp.gnosis.io/session/abc123",
  "transaction": null
}

​
Step 5: Handle Compliance

// Check if auto-completed
if (!onboardingUrl && transaction) {
  console.log('Auto-completed! Skip to monitoring.');
} else if (onboardingUrl) {
  // Show iframe
  const iframe = document.createElement('iframe');
  iframe.src = onboardingUrl;
  iframe.style.cssText = 'width:100%;height:600px;border:none;';
  iframe.allow = 'camera';
  document.getElementById('onboarding-container').appendChild(iframe);

  // Listen for completion
  window.addEventListener('message', (event) => {
    if (!event.origin.includes('ramp.gnosis.io')) return;

    if (event.data.type === 'INTENT_COMPLETED') {
      iframe.remove();
      // Proceed to next step
    }
  });
}

​
Step 6: Execute Transaction

If autoExecute was false, manually trigger execution.

​
API Call

POST /v1/intent/{intentId}/transaction

​
Sample Response

{
  "id": "txn_xyz789",
  "status": "PENDING",
  "depositInstructions": {
    "context": [
      {
        "type": "BANK",
        "instructions": {
          "beneficiary": "Gnosis Ramp",
          "bankName": "Example Bank",
          "accountNumber": "123456789",
          "routingNumber": "021000021",
          "reference": "REF-ABC123"
        }
      }
    ]
  }
}

​
Step 7: Display Deposit Instructions

// Get the bank deposit instructions
const bankInstructions = depositInstructions.context.find(c => c.type === 'BANK');

// Display to user
console.log(`
  Send ${intent.srcAmount} USD to:

  Beneficiary: ${bankInstructions.instructions.beneficiary}
  Bank: ${bankInstructions.instructions.bankName}
  Account: ${bankInstructions.instructions.accountNumber}
  Routing: ${bankInstructions.instructions.routingNumber}

  Reference: ${bankInstructions.instructions.reference}
`);

​
Step 8: Monitor Completion

​
API Call

GET /v1/intent/{intentId}/transaction

​
Sample Response

{
  "id": "txn_xyz789",
  "status": "SUCCESS",
  "srcAmount": "100.00",
  "destAmount": "98.50",
  "completedAt": "2026-03-29T12:00:00.000Z"
}
Poll the endpoint until status is SUCCESS, FAILED, or CANCELLED.

​
Complete Example

async function onramp(userId, walletAddress, amountUsd) {
  // 1. Create customer
  const credentials = btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);
  const customer = await fetch('https://api.ramp.gnosis.io/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ id: userId })
  }).then(r => r.json());

  const accessToken = customer.accessToken;

  // 2. Create intent
  const { intent, onboardingUrl, transaction } = await fetch(
    'https://api.ramp.gnosis.io/v1/intent',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        src: {
          currencyCode: 'USD',
          details: { countryCode: 'US', rail: 'ACH' }
        },
        dest: {
          currencyCode: 'USDC_GNO',
          details: { address: walletAddress }
        },
        srcAmount: amountUsd.toFixed(2),
        autoExecute: true
      })
    }
  ).then(r => r.json());

  // 3. Handle compliance if needed
  if (onboardingUrl) {
    await showComplianceIframe(onboardingUrl);
  }

  // 4. Get deposit instructions
  const txn = await fetch(
    `https://api.ramp.gnosis.io/v1/intent/${intent.id}/transaction`,
    { headers: { 'Authorization': `Bearer ${accessToken}` } }
  ).then(r => r.json());

  return {
    intentId: intent.id,
    depositInstructions: txn.context,
    monitorUrl: `https://api.ramp.gnosis.io/v1/intent/${intent.id}/transaction`
  };
}

​
Next Steps

OFFRAMP Guide

Convert crypto back to fiat.

Webhooks

Get real-time status updates.