Intent Lifecycle

From capability evaluation to onboarding workflows and status polling.

An intent describes the money you want to move between two external accounts. GnosisRamp handles provider selection, compliance orchestration, and workflow execution for you.

1. Create an intent

cURL

curl -X POST https://api.gnosisramp.io/v1/intent \
  -H "Authorization: Bearer $GNOSISRAMP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "srcExternalAccountId": "ext_src",
        "destExternalAccountId": "ext_dest",
        "amount": "100.25",
        "autoExecute": false,
        "redirectUrl": "https://app.yourdomain.com/success",
        "providerId": "provider_123"
      }'

Optional fields:

• autoExecute (boolean, default false) — when true, automatically executes the transaction after compliance completes.
• redirectUrl — URL to redirect users after completing the onboarding flow.
• providerId — preferred provider ID for this intent. Must be a valid candidate for the payment path. Use GET /providers and GET /currencies/supported to discover available provider IDs.

The platform will:

1. Filter eligible providers

   GnosisRamp evaluates your external accounts against each active provider’s capabilities. The metadata from your external accounts — currency, account type, rail, and country — must match the provider’s manifest. Only providers that pass all checks become eligible candidates.

2. Select the provider

   If you specified a providerId, GnosisRamp looks for it among the eligible candidates (returning 400 if it’s not in the list). Otherwise, the first eligible provider is selected. The providerId matches on the Provider.id — the same IDs returned by GET /currencies/supported and GET /providers.

3. Create compliance plan

   The selected provider determines which compliance edges apply, and therefore which KYC/onboarding requirements the user must complete. Different providers may have different compliance flows — for example, one provider might use Sumsub KYC while another has its own onboarding. The response includes a frontendUrl where you can direct users to complete any required onboarding.

4. Execute compliance workflow

   GnosisRamp checks if all compliance requirements are already fulfilled (e.g., returning users who completed KYC previously). If so, the transaction can execute immediately. Otherwise, a workflow starts from the first unfulfilled requirement. Once the plan reaches COMPLETED status, you can proceed with the transaction.

How external accounts affect provider routing

The external accounts you created in the previous step carry the data that drives provider selection:

External Account Metadata    →    Provider Capability Check
─────────────────────────         ────────────────────────
currency.code ("USD")        →    Can handle source currency?
currency.code ("USDC_ETH")   →    Can handle dest currency?
type (BANK_ACCOUNT)          →    Supports this account type?
metadata.rail ("ACH")        →    Supports this rail?
metadata.countryCode ("US")  →    Supports this country?

The providerId is an additional filter on top of capability matching — it says “of all providers that can handle my accounts, use this specific one.” If omitted, GnosisRamp auto-selects.

Why provider choice affects compliance requirements

Different providers have different compliance configurations. For example:

Provider	Compliance Flow	User Experience
Provider A (with Sumsub integration)	Sumsub token share → onboarding	User completes Sumsub KYC widget
Provider B (own KYC)	Provider-native KYC → onboarding	User completes provider’s own KYC flow

This is why providerId matters beyond just routing — it determines the compliance steps your users will see.

Iframe onboarding

For new customers who need to complete compliance steps, the response includes a frontendUrl. You can embed this URL in an iframe to keep users within your application. See the Iframe Integration guide for details on handling postMessage events.

2. Poll or retrieve the intent

Use GET /intent/{id} to check which compliance requirements remain, monitor intent status, or confirm that auto-complete succeeded.

curl -H "Authorization: Bearer $GNOSISRAMP_TOKEN" \
  https://api.gnosisramp.io/v1/intent/int_123

The response includes:

• intent.status – Current status: PENDING, PROCESSING, COMPLETED, etc.
• compliancePlan.steps – Ordered list of compliance requirements with their current status.
• transaction – Transaction details when available (auto-complete or after calling the transaction endpoint).

3. Error signals

Scenario	Behaviour
No providers can handle the route	POST /intent returns 400 with "No provider can handle the requested external accounts". You may need to enable additional providers for your project.
Invalid preferred provider	POST /intent returns 400 with "Preferred provider '{id}' is not a valid candidate for this payment path". The specified providerId cannot handle the requested currency route.
Amount precision mismatch	AmountValidationError with details about allowed decimals (fiat, stablecoin, native tokens, BTC). Adjust the decimal string before retrying.
Requirements failure	The intent is marked as FAILED and the failure reason is available in compliancePlan.steps[].metadata.

Once onboarding passes you can either rely on auto-complete (covered next) or call the transaction API to fetch deposit instructions.