Skip to main content
An intent represents a request to move money between fiat and crypto. This guide covers how to create intents for both ONRAMP and OFFRAMP flows.

​
Request

curl -X POST https://api.ramp.gnosis.io/v1/intent \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

​
Request Fields

FieldTypeRequiredDescription
srcobjectYesSource account details
src.currencyCodestringYesCurrency code (e.g., USD, USDC_GNO)
src.detailsobjectYesAccount-specific fields from requirements schema
destobjectYesDestination account details
dest.currencyCodestringYesCurrency code
dest.detailsobjectYesAccount-specific fields
srcAmountstringYesAmount to transfer (see amount formatting)
providerIdstringNoSpecific provider to use (auto-selected if omitted)
autoExecutebooleanNoAuto-execute transaction after compliance (default: false)
onboardingRedirectUrlstringNoRedirect URL after compliance iframe completion
The type field (e.g., BANK_ACCOUNT, CRYPTO_ADDRESS) is not required in the request — it is auto-computed by the API based on the currency codes. The response will include the resolved type values.
The providerId field goes at the root level of the request, not inside src.details or dest.details.

​
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,
    "failureReason": null,
    "createdAt": "2026-03-29T10:00:00.000Z",
    "updatedAt": "2026-03-29T10:00:00.000Z"
  },
  "onboardingUrl": "https://onboarding.ramp.gnosis.io/session/abc123",
  "transaction": null
}

​
Response Fields

FieldDescription
intentThe created intent object
intent.idUnique intent identifier
intent.statusCurrent status (see Intent Overview)
intent.typeONRAMP or OFFRAMP
intent.providerSelected provider
onboardingUrlURL for compliance iframe (null if auto-completed)
transactionTransaction object if auto-completed, otherwise null

​
Auto-Complete

If the customer has already completed all compliance requirements (e.g., returning customer or KYC sharing): 
{
  "intent": {
    "id": "int_abc123def456",
    "status": "COMPLIANCE_APPROVED"
  },
  "onboardingUrl": null,
  "transaction": {
    "id": "txn_xyz789",
    "status": "PENDING"
  }
}
When transaction is present and onboardingUrl is null, skip the compliance iframe and proceed to monitoring the transaction.

​
ONRAMP vs OFFRAMP

​
ONRAMP (Fiat → Crypto)

{
  "src": {
    "currencyCode": "USD",
    "details": { "countryCode": "US", "rail": "ACH" }
  },
  "dest": {
    "currencyCode": "USDC_GNO",
    "details": { "address": "0x..." }
  },
  "srcAmount": "100.00",
  "autoExecute": true
}

​
OFFRAMP (Crypto → Fiat)

{
  "src": {
    "currencyCode": "USDC_GNO",
    "details": { "address": "0x..." }
  },
  "dest": {
    "currencyCode": "USD",
    "details": { "countryCode": "US", "rail": "ACH" }
  },
  "srcAmount": "100.000000",
  "autoExecute": true
}
For OFFRAMP, the srcAmount uses crypto decimal precision (6 decimals for USDC).

​
Next Steps

Handle Compliance

Show the onboarding iframe to users.

Execute Transaction

Trigger transaction execution.