Skip to main content
An intent represents a request to move money between fiat and crypto. It’s the central concept in Gnosis Ramp.

​
Intent Types

TypeDescriptionExample
ONRAMPFiat → CryptoUSD → USDC on Gnosis Chain
OFFRAMPCrypto → FiatUSDC on Gnosis Chain → USD

​
Key Concepts

​
Source and Destination

Every intent has:
  • Source (src) — Where the money comes from
  • Destination (dest) — Where the money goes
For ONRAMP:
  • Source: Bank account (fiat)
  • Destination: Wallet address (crypto)
For OFFRAMP:
  • Source: Wallet address (crypto)
  • Destination: Bank account (fiat)

​
Amount

The srcAmount specifies how much to transfer from the source. Amounts are strings with currency-specific decimal precision. See Amount Formatting for details.

​
Intent Lifecycle

  1. Quote (Recommended) — Fetch indicative pricing to compare providers
  2. Requirements — Fetch field schemas for the currency pair
  3. Create — Submit intent with source, destination, and amount
  4. Compliance — User completes any required onboarding/KYC
  5. Execute — Transaction is initiated
  6. Complete — Money movement finishes
Getting a quote is optional but recommended for better UX. It lets users compare rates across providers before committing to an intent. See Getting a Quote for details.

​
Intent Status Lifecycle

An intent progresses through a defined set of statuses as it moves from creation through compliance to transaction completion.
EXPIRED and CANCELLED can occur from any non-terminal state and are not shown in the diagram for clarity.

​
Intent Statuses

StatusDescriptionTerminal?
CREATEDIntent created, waiting to start complianceNo
COMPLIANCE_IN_PROGRESSCustomer completing onboarding/KYCNo
COMPLIANCE_APPROVEDCompliance passed (transient state)No
COMPLIANCE_FAILEDKYC/compliance rejectedYes
PENDING_PAYMENTReady for transaction executionNo
TRANSACTION_IN_PROGRESSTransaction executing with providerNo
TRANSACTION_FAILEDTransaction failed at providerYes
COMPLETEDFunds settled successfullyYes
EXPIREDIntent timed outYes
CANCELLEDIntent cancelledYes
The failureReason field is populated when an intent reaches a terminal failure state (COMPLIANCE_FAILED or TRANSACTION_FAILED), providing details about why the intent failed.

​
Quick Example

# Create an ONRAMP intent (USD → USDC)
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
  }'

​
Next Steps

Currencies & Providers

Discover available currency pairs.

Get a Quote

Compare pricing across providers.

Get Requirements

Learn what fields are needed for each intent.

ONRAMP Guide

Complete fiat-to-crypto walkthrough.

OFFRAMP Guide

Complete crypto-to-fiat walkthrough.