Withdraw Collateral

Fetch a user’s collateral contract and admin withdrawal signature, then sign and submit the withdrawal on-chain.

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.

1. 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:

   iOS

   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
   )
   

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

   iOS

   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)
   

   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.

iOS

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

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

iOS

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
)

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

Withdraw Collateral (Guide)

Contract architecture and server-side withdrawal examples.

Authentication

Configure the built-in Rain API client and session tokens.

Error Reference

Handle SDK errors with standardized error codes.