Withdraw Collateral

Withdraw collateral from your app in two steps: get an admin signature from the Rain API, then sign and submit on-device. The SDK runs the entire on-chain portion for you: it builds the EIP-712 message, encodes the calldata, signs through the resolved wallet, and submits the transaction. The SDK’s built-in Rain API client can fetch the signature itself, so the whole flow can run in-app. Alternatively, your backend fetches the signature and forwards it to the app. For background on how collateral contracts work, see Withdraw Collateral and Managing Collateral.

Withdrawal flow overview

The full round trip looks like this:

The steps above, in text:

#	From → To	Message
1	App → Rain API	Get withdrawal signature (built-in client, or via your backend)
2	Rain API → App	Admin signature, salt, expiresAt
3	App → RainClient	`withdrawCollateral(...)`
4	RainClient → Chain	Check admin authorization, sign via wallet, and submit
5	Chain → App	Transaction hash

Getting the admin signature requires Rain API credentials. Use the built-in Rain API client with a runtime-delivered, scoped key, or keep the call server-side with your primary Api-Key and forward the result. Never ship your primary Api-Key in a mobile app.

Get the contract and admin signature

With the built-in Rain API client configured, fetch the user’s collateral contract and the admin signature directly in the app:

let contract = try await rain.fetchCollateralContract()

let adminSignature = try await rain.fetchAdminSignature(
    chainId: contract.chainId,
    tokenAddress: tokenAddress,
    amountBaseUnits: BigUInt(1_000_000),   // token base units
    adminAddress: contract.adminAddresses[0],
    recipientAddress: recipientAddress
)

val contract = rain.fetchCollateralContract()

val adminSignature = rain.fetchAdminSignature(
    chainId = contract.chainId,
    tokenAddress = tokenAddress,
    amountBaseUnits = BigInteger("1000000"),   // token base units
    adminAddress = contract.adminAddresses.first(),
    recipientAddress = recipientAddress,
)

If Rain hasn’t produced the signature yet, the SDK throws RAIN_303 carrying the reported status and an optional retryAfter hint: retry after that interval.Alternatively, fetch the signature from your backend with the server-side SDK and pass the salt / signature / expiresAt values into the app; the on-chain step is identical:

TypeScript

const signature = await client.users.signatures.retrieveWithdrawalSignature(
  userId,
  {
    token: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
    adminAddress: "0x1234...5678",
    amount: "1000000", // in token base units
    recipientAddress: "0xabcd...ef01",
  },
);
// Pass signature.salt, signature.signature, and signature.expiresAt to your app.

Withdraw

Pass the admin signature to withdrawCollateral. The SDK builds the transaction, signs it through the resolved wallet (the provider must support typed-data signing), submits it, and returns the transaction hash.

let addresses = WithdrawAssetAddresses(
    contractAddress: contract.controllerAddress,
    proxyAddress: contract.proxyAddress,
    recipientAddress: recipientAddress,
    tokenAddress: tokenAddress
)

let txHash = try await client.withdrawCollateral(
    chainId: contract.chainId,
    assetAddresses: addresses,
    amount: 1,
    decimals: 6,
    salt: adminSignature.salt,             // base64
    signature: adminSignature.signature,   // hex, 65 bytes
    expiresAt: adminSignature.expiresAt,
    nonce: nil                             // the latest nonce is always read on-chain
)
print(txHash)

import com.rain.sdk.models.RainWithdrawAddresses

val addresses = RainWithdrawAddresses(
    proxyAddress = contract.proxyAddress,
    controllerAddress = contract.controllerAddress,
    tokenAddress = tokenAddress,
    recipientAddress = recipientAddress,
)

val result = client.withdrawCollateral(
    chainId = contract.chainId,
    addresses = addresses,
    amount = BigDecimal("1"),
    decimals = 6,
    adminSignature = adminSignature,   // RainAdminSignature(salt, signature, expiresAt)
    nonce = null,                      // omit to read the latest nonce on-chain
    autoSend = true,
)
println(result.transactionHash)

Platform differences:

Behavior	iOS	Android
Admin signature	`salt`, `signature`, `expiresAt` parameters	`RainAdminSignature(salt, signature, expiresAt)`
Address model	`WithdrawAssetAddresses` (contract, proxy, recipient, token)	`RainWithdrawAddresses` (proxy, controller, token, recipient)
Nonce	A caller-supplied `nonce` is currently ignored: the latest nonce is always read on-chain (`rain.buildEIP712Message` does honor an explicit nonce)	`nonce` parameter; `null` reads the latest on-chain
Auto-send	Always sends (returns the tx hash `String`)	`autoSend` parameter (default `false`); leave `false` to get `transactionData` for manual submission
Return type	`String` (transaction hash)	`RainWithdrawResult` with `transactionHash` or `transactionData`

On Android, addresses are checksummed and validated up front: malformed input throws RAIN_102.

Before signing, the SDK checks on-chain that the resolved wallet is one of the collateral’s admin signers. A wallet that is definitively not authorized throws RAIN_407 (naming the wallet and proxy) before any signing round-trip, instead of an opaque on-chain InvalidSignature() revert. If the check cannot run (RPC failure), the withdrawal proceeds.

Estimate the withdrawal fee

Estimate the network fee before submitting.

let fee: Decimal = try await client.estimateWithdrawalFee(
    chainId: contract.chainId,
    addresses: addresses,
    amount: 1,
    decimals: 6,
    salt: adminSignature.salt,
    signature: adminSignature.signature,
    expiresAt: adminSignature.expiresAt
)
// estimated cost in the chain's native token

val fee: Double = client.estimateWithdrawalFee(
    chainId = contract.chainId,
    addresses = addresses,
    amount = 1.0,
    decimals = 6,
    adminSignature = adminSignature,
)
// estimated cost in the chain's native token

Fee estimation builds the full transaction, including an EIP-712 signTypedData call through the provider. That means estimate-then-withdraw signs twice, and estimation can surface a signing prompt (for example biometrics on Turnkey). The collateral-admin check also runs during estimation, so RAIN_407 is possible here too. iOS returns Decimal; Android returns Double.

Manual building (bring your own submission)

To build the withdrawal calldata yourself and submit with your own wallet, use the wallet-agnostic builders: they never resolve a provider (though Android’s build() still requires at least one registered).

let (messageJson, saltHex) = try await rain.buildEIP712Message(
    chainId: chainId,
    walletAddress: walletAddress,
    assetAddresses: EIP712AssetAddresses(proxyAddress: proxy, recipientAddress: recipient, tokenAddress: token),
    amount: 1,
    decimals: 6,
    nonce: nil
)
// Sign messageJson with your wallet → signatureData (65-byte Data).
// Decode to Data: saltHex (hex), adminSignature.salt (base64), adminSignature.signature (hex).
let calldata = try await rain.buildWithdrawTransactionData(
    chainId: chainId,
    assetAddresses: addresses,
    amount: 1,
    decimals: 6,
    expiresAt: adminSignature.expiresAt,
    salt: saltData,
    signatureData: signatureData,
    adminSalt: adminSaltData,
    adminSignature: adminSignatureData
)

val builder = rain.transactionBuilder

val nonce = builder.getLatestNonce(rpcUrl, proxyAddress)
val isAdmin = builder.isCollateralAdmin(rpcUrl, proxyAddress, walletAddress)  // null = unknown
val (messageJson, salt) = builder.buildEIP712Message(chainId, addresses, walletAddress, amount, decimals, nonce)
// sign messageJson with your wallet, then:
val calldata = builder.buildWithdrawTransactionData(addresses, amount, decimals, salt, signatureData, adminSignature)

Error handling

Withdrawal methods can throw:

Code	Meaning
RAIN_101	SDK not built, or no wallet provider resolved
RAIN_303	Admin signature not ready yet (retry after `retryAfter`)
RAIN_401	User cancelled the signing request
RAIN_402	Insufficient funds for gas
RAIN_403	Transaction simulation reverted before submission
RAIN_405	Withdrawal reverted on-chain (duplicate or already-used signature)
RAIN_407	Signing wallet is not a collateral admin
RAIN_502	EIP-712 / internal encoding error

See the full Error Reference for handling patterns.

What’s next