Withdrawals

Read endpoints for withdrawals use deposits.read scope. Create still requires withdrawals.write.

Overview

GET /partner/v1/withdrawals/assets: list destination assets.
POST /partner/v1/withdrawals/range: get min/max for a destination pair.
POST /partner/v1/withdrawals/estimate: quote destination receive amount for a given amount.
POST /partner/v1/withdrawals: create relay + fetch Rain withdrawal signature payload.

POST /partner/v1/withdrawals uses a breaking request body shape with source and destination objects.

Withdrawal routes are dynamic (BTC/SOL/EVM and others) and can change. Always call assets, range, and estimate before create. In sandbox, source is fixed to rUSD on Base Sepolia. source.contractId is optional.

Flow

API flows (step-by-step)

1) Discover destination assets

Endpoint: GET /partner/v1/withdrawals/assets

curl -s \
  -H "Authorization: Bearer $PARTNER_SESSION_TOKEN" \
  "https://api.machines.cash/partner/v1/withdrawals/assets?q=hbar&limit=20"

You can optionally pass sourceChainId and sourceTokenAddress as hints, but they are not required.

2) Get min/max for chosen route

Endpoint: POST /partner/v1/withdrawals/range

curl -s \
  -H "Authorization: Bearer $PARTNER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": { "currency": "hbar", "network": "hbar" }
  }' \
  https://api.machines.cash/partner/v1/withdrawals/range

3) Estimate destination receive amount

Endpoint: POST /partner/v1/withdrawals/estimate

curl -s \
  -H "Authorization: Bearer $PARTNER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": { "currency": "hbar", "network": "hbar", "extraId": "optional-tag" },
    "amountCents": 2500
  }' \
  https://api.machines.cash/partner/v1/withdrawals/estimate

4) Create withdrawal signature payload (breaking schema)

Endpoint: POST /partner/v1/withdrawals

curl -s \
  -H "Authorization: Bearer $PARTNER_SESSION_TOKEN" \
  -H "Idempotency-Key: wdrl-123456" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 2500,
    "source": {
      "contractId": "optional-uuid"
    },
    "destination": {
      "currency": "hbar",
      "network": "hbar",
      "address": "0.0.123456",
      "extraId": "optional-tag"
    },
    "adminAddress": "0x..."
  }' \
  https://api.machines.cash/partner/v1/withdrawals

Ready responses include:

execution info for contract call routing.
relay metadata (payinAddress, payinExtraId, payoutAddress, payoutExtraId, route ids).

5) Execute onchain

from must be the same admin EOA used in the create request (adminAddress).
to must be execution.callTarget (controller or coordinator), not the collateral proxy address.
Use parameters in order: [collateralProxy, token, amount, recipient, expiresAt, executorSalt, executorSignature].
If execution.callPath = controller_v1, call 7-arg withdrawAsset(…).
If execution.callPath = coordinator_v2, call 10-arg withdrawAsset(…) and include v2 admin signature values.
If status is pending, wait retryAfterSeconds and retry the same request with the same idempotency key.

Onchain execution details

For coordinator_v2, you must generate an additional admin signature before calling the contract.

// response from POST /partner/v1/withdrawals
const { data } = withdrawalResponse;
if (data.status !== "ready" || !data.parameters || !data.execution?.callTarget) {
  throw new Error("withdrawal signature is not ready");
}

const [collateralProxy, token, amount, recipient, expiresAt, executorSalt, executorSignature] =
  data.parameters;

// tx sender must match adminAddress used in create request
const adminAddress = "0x..."; // same value you sent as adminAddress

if (data.execution.callPath === "controller_v1") {
  // to = data.execution.callTarget
  await controller.withdrawAsset(
    collateralProxy,
    token,
    amount,
    recipient,
    expiresAt,
    executorSalt,
    executorSignature,
  );
} else if (data.execution.callPath === "coordinator_v2") {
  // 1) Read nonce from collateral proxy
  const nonce = await collateral.adminNonce();

  // 2) Build typed data
  const adminSalt = randomBytes(32);
  const domain = {
    name: "Collateral",
    version: "2",
    chainId: data.execution.chainId,
    verifyingContract: collateralProxy,
    salt: hexlify(adminSalt),
  };
  const types = {
    Withdraw: [
      { name: "user", type: "address" },
      { name: "asset", type: "address" },
      { name: "amount", type: "uint256" },
      { name: "recipient", type: "address" },
      { name: "nonce", type: "uint256" },
    ],
  };
  const message = {
    user: adminAddress,
    asset: token,
    amount: BigInt(amount),
    recipient,
    nonce,
  };
  const adminSignature = await signer.signTypedData(domain, types, message);

  // 3) Call coordinator (to = data.execution.callTarget)
  await coordinator.withdrawAsset(
    collateralProxy,
    token,
    amount,
    recipient,
    expiresAt,
    executorSalt,
    executorSignature,
    [adminSalt],
    [adminSignature],
    true,
  );
}

Relay metadata fields

string

Provider exchange id for relay tracking.

string

Address Rain withdrawal sends funds to.

string

Optional memo/tag required on relay pay-in side.

string

Final destination address configured on the relay.

string

Optional destination memo/tag configured for payout.

Updates

Start

Wallet Providers

Core Flows

Legal

Agentic

Reference

Authentication API

Users API

KYC API

Agreements API

Cards API

Encryption API

Balances API

Deposits API

Transactions API

Withdrawals API

Overview

Flow

API flows (step-by-step)

Onchain execution details

Relay metadata fields

​Overview

​Flow

​API flows (step-by-step)

​Onchain execution details

​Relay metadata fields

Overview

Flow

API flows (step-by-step)

Onchain execution details

Relay metadata fields