Collateral Funding

Beta FeatureThe Transaction Simulations feature is currently in beta. API endpoints and behavior may change as we continue to refine the product. Simulation endpoints are available in development environments only — production returns 404 Not Found.

Trigger a collateral deposit to a smart contract, exactly as if a real on-chain transfer had occurred. Use this to test your collateral webhook handling and balance updates without executing actual blockchain transactions.

Endpoint

POST /v1/simulate/collateral/fund

This endpoint simulates adding rUSD collateral to a smart contract. The simulation mints rUSD to the contract’s on-chain proxy address in the sandbox environment, which triggers the existing collateral-add pipeline and fires transaction.collateral.created webhooks.

Supported chains

Collateral simulation is only available in the sandbox environment. The following testnet chains are supported:

Ethereum Sepolia
Avalanche Fuji
Solana Devnet
Polygon Amoy
Base Sepolia

Headers

Header	Type	Required	Description
`Api-Key`	string	Yes	Your tenant API key. The tenant scope is resolved from this key.
`Content-Type`	`application/json`	Yes	—

Body

Field	Type	Required	Description
`contractId`	string (UUID)	Yes	The collateral contract ID to fund. Must belong to your tenant or be an operator-owned contract for your tenant.
`currency`	string	Yes	The currency to simulate. Currently only `"rusd"` is supported.
`amount`	integer	Yes	The amount in cents (USD minor units). For example, `10000` represents $100.00. Must be zero or greater.

Example request

{
  "contractId": "b8c3d4e5-6f7a-4b2c-9d1e-3f4a5b6c7d8e",
  "currency": "rusd",
  "amount": 10000
}

Response

A successful response returns a transaction ID for tracking purposes.

200 OK

{
  "transactionId": "f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9"
}

Field	Type	Description
`transactionId`	string (UUID)	A correlation ID for the simulation request. The actual `CollateralAdd` transaction is created downstream when the blockchain listener processes the simulated on-chain transfer.

After calling this endpoint, the simulation mints rUSD to the contract’s proxy address. The blockchain listener detects this transfer and runs the standard collateral-add pipeline, which:

Creates a CollateralAdd transaction record
Updates the team balance
Fires the transaction.collateral.created webhook

See the transaction.collateral.created webhook reference for payload schemas.

Errors

Status	When
`400 Bad Request`	Invalid body — missing required fields, unsupported currency, or negative amount.
`404 Not Found`	Endpoint not available in production, feature not enabled for your tenant, or the contract does not exist or belong to your tenant.
`422 Unprocessable Entity`	The contract’s chain is not supported, or rUSD is not available on the contract’s chain.
`500 Internal Server Error`	Unhandled error during simulation.

Behavior notes

Sandbox only. This endpoint returns 404 Not Found in production environments.
Real collateral record. The simulation creates a real collateral transaction that is queryable via the standard transactions API and fires the same webhooks as a real deposit.
Immediate settlement. In the sandbox environment, simulated transfers settle immediately without requiring actual funds.

Example

curl -X POST https://api-dev.rain.xyz/v1/simulate/collateral/fund \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "b8c3d4e5-6f7a-4b2c-9d1e-3f4a5b6c7d8e",
    "currency": "rusd",
    "amount": 10000
  }'

Introduction

Plan & Set Up Your Program

Build Your Program

Run Your Program

Rewards

Embedded Wallets

Collateral Funding

Endpoint

Supported chains

Headers

Body

Response

Errors

Behavior notes

Example

​Endpoint

​Supported chains

​Headers

​Body

​Response

​Errors

​Behavior notes

​Example

Endpoint

Supported chains

Headers

Body

Response

Errors

Behavior notes

Example