Kevo Docs

Fiat Onramp

Let users buy crypto with a card or bank transfer and receive it directly to their Kevo wallet. Kevo creates a hosted onramp session with the configured provider and returns a URL you can open in a popup or redirect.

Supported providers

Stripe

Crypto onramp. Live.

MoonPay

Coming soon (501).

Transak

Coming soon (501).

Enable in your project

json
{
  "onramp": {
    "enabled": true,
    "provider": "stripe",
    "allowedChainIds": [1, 137, 8453],
    "allowedAssets": ["usdc", "eth"]
  }
}
ℹ
Leave allowedChainIds / allowedAssets unset to allow any combination supported by the provider.

Create a session

The SDK does not ship a dedicated onramp helper yet — call the endpoint directly with the user's access token. Open the returned url in a popup or iframe; the provider handles KYC, payment, and on-chain delivery.

typescript
import { useKevo } from '@kevo-ws/sdk/react'

function BuyUsdc() {
  const { client } = useKevo()

  const handle = async () => {
    const token = await client.getValidAccessToken()
    const res = await fetch('https://api.kevo.ws/v1/wallets/me/onramp/session', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        asset: 'usdc',
        network: 'ethereum',
        chainId: 1,
        fiatAmount: '50.00',
        fiatCurrency: 'usd',
      }),
    })
    const { url } = await res.json()
    window.open(url, 'kevo-onramp', 'width=480,height=720')
  }

  return <button onClick={handle}>Buy USDC</button>
}

HTTP API

POST/v1/wallets/me/onramp/sessionBearer (user)

Create a hosted onramp session targeting the user's Kevo wallet.

Request

ts
{
  asset: string             // e.g. 'usdc', 'eth'
  network: string           // provider slug e.g. 'ethereum', 'polygon', 'solana'
  chainId?: number          // omit for Solana
  fiatAmount?: string       // /^\d+(\.\d{1,2})?$/
  fiatCurrency?: string     // ISO-4217 (default 'usd')
}

Response 200

ts
{
  sessionId: string             // Kevo session id
  providerSessionId: string
  provider: 'stripe' | 'moonpay' | 'transak'
  url: string                   // open in popup / redirect
  expiresAt: string | null      // ISO 8601
}

Errors

ts
400 { error: <zod issues> }
403 { error: 'Onramp is not enabled for this project'
            | 'Chain X is not in the onramp allowlist'
            | 'Asset X is not in the onramp allowlist' }
404 { error: 'EVM wallet not found' | 'Solana wallet not found' }
501 { error: 'Provider not implemented' }     // moonpay/transak
502 { error: 'Onramp provider unavailable' }
503 { error: 'Onramp provider not configured' }

Webhooks

Onramp events are dispatched to all configured webhooks for the project. Use them to update your UI, credit balances, or trigger downstream flows.

onramp.session_created

Fired right after the session is created. Includes sessionId, provider, url.

onramp.completed

Fiat payment received and crypto on its way (Stripe webhook).

onramp.failed

Provider reported a payment or KYC failure.

Operator setup

The API needs the provider credentials configured for the chosen provider.

bash
# packages/api/.env  (Stripe)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...