Onramps

Endpoint MigrationThe /v1/automations endpoints have been renamed to /v1/payment-routes. The old /v1/automations paths remain available as deprecated aliases during migration. Update your integrations to use /v1/payment-routes as the deprecated endpoints will be removed in a future release.

Overview

Onramps let your users convert fiat to stablecoin through a persistent payment route. When you create an onramp payment route, Rain generates a virtual account with unique banking credentials. Any funds sent to that virtual account are automatically converted to the destination stablecoin and delivered to the destination onchain address.

If you’re funding a Rain-Managed program’s collateral contract specifically, Rain also offers a dedicated onramp flow built on the contracts API, which returns ACH, RTP, and wire details together instead of a single virtual account.

Before you begin

Make sure you have:

API access to the payment routes endpoints.
A destination address: an onchain wallet address where converted stablecoin is delivered. This can be a Rain smart contract or an external wallet.
A US bank account: your end users need one to initiate fiat transfers.

Restrictions

Onramp payment routes are subject to the same restrictions & availability rules as any other payment route, plus Rain’s Payments compliance checks.

Key concepts

Payment routes

A payment route creates a persistent pipe between a source and destination. For onramps:

Source: fiat via ACH or wire transfer.
Destination: an onchain address on a supported chain.

When you create an onramp payment route, Rain generates a depositAddress containing virtual account banking credentials. This virtual account acts as the named beneficiary for incoming fiat transfers. See What a payment route is for how Rain determines direction for both onramps and offramps.

Virtual accounts

Virtual accounts are dedicated banking credentials that Rain generates for receiving fiat transfers, not payment accounts you register yourself. Each onramp payment route generates its own virtual account, giving your users unique ACH and wire transfer details.

First-party and third-party transfers

Virtual accounts support both first-party and third-party incoming transfers:

First-party: the user who owns the payment route sends funds from their own bank account.
Third-party: a different party sends funds to the virtual account on behalf of the user, for example an employer funding an employee’s account.

API flow

Action / API callExternal / userWebhook Rain sends you

The steps above, in text:

#	Actor	Step
–	User	Requests banking details from the partner
1	Partner	Calls `POST /payment-routes`
2	Rain	Returns the route with a `depositAddress`
3	Partner	Provides the virtual account details to the user
4	User	Sends an ACH or wire transfer to the virtual account
5	Rain	Converts the fiat to stablecoin
6	Destination	Receives the stablecoin deposit onchain
7	Rain	Sends a `transactionTransfer` webhook

Create an onramp payment route

To create an onramp payment route, call POST /payment-routes with a fiat source and an onchain destination. See Create an onramp payment route for the full request, response, and field reference; the shape is identical for onramps created from this page.

Destination address formatThe destination address must match the expected format for the destination rail:

EVM chains (Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, Celo): must be a valid EVM address starting with 0x followed by 40 hexadecimal characters (for example, 0x1234567890abcdef1234567890abcdef12345678).
Solana: must be a valid Solana address in base58 format (32-44 characters).

If the address doesn’t match the destination rail format, the request fails.

Manage payment routes

Use GET /payment-routes, GET /payment-routes/{paymentRouteId}, and DELETE /payment-routes/{paymentRouteId} to list, retrieve, and remove onramp payment routes. See Manage payment routes for the full request and response examples.

Deleting a payment route invalidates the associated virtual account. Any subsequent transfers to those banking credentials fail. Notify your users before deleting a payment route.

What happens when funds are received

When a user sends funds to the virtual account:

Funds received: Rain receives the fiat transfer at the virtual account. Deposits under $2.00 don’t create a transfer.
Transfer created: Rain creates a transaction of type transfer and sends a transactionTransfer webhook with action created.
Conversion: Rain automatically converts funds to the destination stablecoin.
Transfer: Rain sends stablecoin to the destination onchain address.
Transfer completed: the transfer reaches a final state, and Rain sends a transactionTransfer webhook with action completed.

Webhooks

Rain sends webhooks through the transfer lifecycle:

Resource	Action	Description
`transactionTransfer`	`created`	Sent when the transfer is initiated after funds are received
`transactionTransfer`	`updated`	Sent when the transfer’s status changes during processing
`transactionTransfer`	`completed`	Sent when the transfer settles and crypto is delivered

See the transfer object reference for the full webhook payload schema.

Transfer transaction

Each successful onramp creates a transfer transaction that you can query via the Transactions API. Filter by type=transfer to see all transfer transactions:

curl -X GET "https://api.rain.xyz/v1/issuing/transactions?type=transfer" \
  -H "Api-Key: YOUR_API_KEY"

Example transfer transaction response:

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "type": "transfer",
  "transfer": {
    "source": {
      "amount": "100.00",
      "currency": "usd",
      "rail": "ach"
    },
    "destination": {
      "amount": "99.50",
      "currency": "usdc",
      "rail": "base",
      "address": {
        "type": "onchain",
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    },
    "depositAddress": {
      "type": "fiat",
      "beneficiaryName": "JOHN DOE",
      "beneficiaryAddress": "123 Main St, Austin, TX 78701, US",
      "beneficiaryBankName": "Partner Bank, N.A.",
      "beneficiaryBankAddress": "456 Bank Ave, New York, NY 10002, US",
      "accountNumber": "9876543210",
      "routingNumber": "021000021"
    },
    "exchangeRate": 1.0,
    "status": "settled",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:45:00Z"
  }
}

To list the transfer transactions for a specific user, see Viewing Transactions.

Settlement times

Transfer times vary by rail:

Rail	Typical settlement
ACH	1-3 business days
Wire	Same business day

After fiat settlement, the conversion and onchain transfer typically complete within minutes.

Cutoff times

Fiat transfer processing is subject to banking cutoff times. Transfers received after the cutoff are processed on the next business day.

Rail	Cutoff Time	Notes
ACH (Same-Day)	4:00 PM ET	Transfers submitted after this cutoff are processed the next business day
Wire (Fedwire)	5:45 PM ET	Transfers submitted after this cutoff are processed the next business day

Cutoff times apply on US business days only. Transfers initiated on weekends or US federal holidays are processed on the next business day.

Supported configurations

Source (fiat)

Currency	Rails
USD	ACH, Wire

Destination (crypto)

Currency	Rails (Chains)
USDC	Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, Celo, Solana
RUSD	Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, Celo, Solana

Rain regularly adds additional currencies and chains. Contact your Rain representative for the latest supported configurations.

Error handling

Common error scenarios when creating a payment route:

Error	Description	Resolution
`invalid_destination_address`	The destination address format doesn’t match the rail	Use an EVM address for EVM rails or Solana for Solana
`unsupported_currency_pair`	The source/destination currency combination is not supported	Check supported configurations above
`unsupported_rail`	The specified rail is not available	Use a supported rail for the currency

Best practices

Monitor webhooks: set up webhook handlers to track transfer status in real time instead of polling.
Handle failures gracefully: fiat transfers can fail due to bank issues on the sender’s side. Implement retry logic and user notifications.
Validate destination addresses client-side: catch malformed onchain addresses before calling POST /payment-routes to avoid a round trip on an avoidable error.

What’s next

Payment routes

See the full request, response, and field reference shared by onramps and offramps.

Set up offramps

Enable fiat withdrawals from crypto.

Onramp to Rain Contract

Fund a Rain-Managed program’s collateral contract directly instead.

Set up webhooks

Receive transfer notifications as they happen.

Introduction

Set Up Money Movement

Money Movement

Subtenants

Reconciliation

Overview

Before you begin

Restrictions

Key concepts

Payment routes

Virtual accounts

First-party and third-party transfers

API flow

Create an onramp payment route

Manage payment routes

What happens when funds are received

Webhooks

Transfer transaction

Settlement times

Cutoff times

Supported configurations

Source (fiat)

Destination (crypto)

Error handling

Best practices

What’s next

Payment routes

Set up offramps

Onramp to Rain Contract

Set up webhooks

​Overview

​Before you begin

​Restrictions

​Key concepts

​Payment routes

​Virtual accounts

​First-party and third-party transfers

​API flow

​Create an onramp payment route

​Manage payment routes

​What happens when funds are received

​Webhooks

​Transfer transaction

​Settlement times

​Cutoff times

​Supported configurations

​Source (fiat)

​Destination (crypto)

​Error handling

​Best practices

​What’s next

Payment routes

Set up offramps

Onramp to Rain Contract

Set up webhooks

Overview

Before you begin

Restrictions

Key concepts

Payment routes

Virtual accounts

First-party and third-party transfers

API flow

Create an onramp payment route

Manage payment routes

What happens when funds are received

Webhooks

Transfer transaction

Settlement times

Cutoff times

Supported configurations

Source (fiat)

Destination (crypto)

Error handling

Best practices

What’s next