> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Collateral Funding

> Simulate collateral deposits to test your collateral webhook handling.

<Warning>
  **Beta Feature**

  The 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`.
</Warning>

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
```

<Info>
  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.
</Info>

## 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.        |

```json title="Example request" theme={null}
{
  "contractId": "b8c3d4e5-6f7a-4b2c-9d1e-3f4a5b6c7d8e",
  "currency": "rusd",
  "amount": 10000
}
```

## Response

A successful response returns a transaction ID for tracking purposes.

```json title="200 OK" theme={null}
{
  "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. |

<Info>
  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](/changelog/webhooks/v1/transaction/collateral/created) for payload schemas.
</Info>

## 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

```bash theme={null}
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
  }'
```