Collateral Funding

Simulate collateral deposits to test your collateral webhook handling.

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 between 0 and 2147483647.

Example request

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

Response

A successful response returns 202 Accepted. The response carries no transaction ID, because the CollateralAdd transaction is created downstream when the blockchain listener processes the simulated on-chain transfer.

202 Accepted

{
  "success": true
}

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, rUSD is not available on the contract’s chain, or the contract has no proxy address yet.
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
  }'