Withdraw Funds

Withdrawals in Rails Yield are not instant. Bitcoin is committed to Lightning channels and Magma leases; to release it, channels must close or leases must unwind. You signal intent by raising a withdrawal target, and automation drains liquidity back to on-chain balance over time.

Sequence

Password hash

The withdrawal mutation requires the master-account password_hash, derived client-side from the account password using Argon2id (master key + password as salt). The hash is sent to the server, never the plaintext password. See Security for the derivation details.

Mutation

mutation IncreaseWithdrawalTarget($input: IncreaseWithdrawalInput!) {
  node {
    withdrawal {
      increase_withdrawal_target(input: $input) {
        amount
      }
    }
  }
}

curl -X POST https://rails.amboss.tech/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AMBOSS_DASHBOARD_TOKEN" \
  -d '{
    "query": "mutation($input: IncreaseWithdrawalInput!) { node { withdrawal { increase_withdrawal_target(input: $input) { amount } } } }",
    "variables": {
      "input": {
        "node_id": "<NODE_ID>",
        "amount_sats": "5000000",
        "password_hash": "<argon2id-derived hash>"
      }
    }
  }'

const { node } = await client.request(INCREASE_WITHDRAWAL_TARGET, {
  input: {
    node_id: process.env.NODE_ID,
    amount_sats: "5000000",
    password_hash: passwordHash,
  },
});
console.log("new target:", node.withdrawal.increase_withdrawal_target.amount);

IncreaseWithdrawalInput

Tracking progress

Poll withdrawal_target and funds.available until they converge:

query WithdrawalProgress($nodeId: String!, $input: LiquidityProviderInput) {
  node {
    deployed_node(node_id: $nodeId) {
      withdrawal_target
      funds_available_at
    }
  }
  user {
    liquidity_provider(input: $input) {
      funds {
        available { sats usd }
        reserved  { sats usd }
        total     { sats usd }
      }
    }
  }
}

Move funds to your wallet

Once funds.available.sats covers the target, send the Bitcoin out using the LND macaroon directly - Rails does not handle the on-chain send. From the dashboard, the "Withdraw" dialog walks through this; from the API:

curl --header "Grpc-Metadata-macaroon: $MACAROON_HEX" \
  -X POST $LND_REST/v1/transactions \
  -d '{"addr":"bc1q...","amount":"5000000","sat_per_vbyte":"5"}'

The Rails-issued macaroon does not grant on-chain spend. For Fully Managed nodes, withdrawals route through Rails' withdrawal pipeline (triggered by the increase_withdrawal_target mutation); for Third Party Hosted you spend with your own admin macaroon.

Common scenarios

Partial withdraw

Set amount_sats to less than the total balance. Automation will close just enough channels to cover the request, preserving routing capacity.

Max withdraw

Set amount_sats to funds.total.sats - funds.available.sats (i.e. the reserved portion). All channels will close.

Cancelling a target

There is no direct "decrease" mutation; the target is monotonically increasing. Practically, contact support before a large change-of-mind to avoid unnecessary channel closures.

Error reference

Next steps

• Security - password hash derivation in detail
• Monitor - poll funds and projection
• LND API - move funds on-chain once available