Skip to main content
POST
Create or update a rule
Set up an automatic sweep: whenever your balance for currency reaches minAmount, it is sent automatically to destination.
Once a rule is enabled, funds leave your account automatically when the threshold is hit. The destination must already be on your withdrawal whitelist for that currency — the check runs server-side, so a stolen dashboard session alone cannot point a rule at an unknown address.
Egress (outbound money movement) is fee-free: you pay the network cost only, with no platform markup.

Authorization

Dashboard-only (JWT) with role merchant_admin, merchant_member or super_admin, plus the auto-withdrawals:manage team permission. API keys are not accepted — an API key gets 401 {"error":"Invalid or expired token"}. Because this call configures automatic money movement, the body must carry one fresh MFA factor (passkey / TOTP / emailed code — the VERIFICATION_PROPS fields; see the Authentication guide). Email codes come from Send auto-withdrawal email code. Rate limit: 10/min.

Body parameters

string
required
The currency the rule applies to — one rule per currency. 2–20 characters.
string
required
The balance threshold, as a decimal string (1–40 characters). When your balance for currency reaches this amount, the rule fires.
string
required
Where the funds go (4–256 characters). The whitelist check runs when the rule is enabled (enabled: true) and again on every execution: an enabled rule whose destination is not whitelisted for currency is rejected with NOT_WHITELISTED. A paused rule (enabled: false) can be saved with a destination that is not currently whitelisted — it just cannot be enabled or fire until the destination is whitelisted.
boolean
required
Whether the rule is active. The field is required — pass false to create the rule in a paused state.
string
"fixed" or "all" (default "all"). With "fixed" the rule withdraws exactly minAmount each time it fires; with "all" it sweeps the full available balance.
string
Routing tag for tag-based currencies (XRP): a decimal string of up to 10 digits. The (currency, destination, destinationTag) triple must be whitelisted. Omitting it on an update removes a previously stored tag.
In addition to the rule fields, the body must include one fresh MFA factor:
string
The single-use emailed code.
string
A 6-digit code from your authenticator app — an alternative to emailCode. Backup codes are not accepted here: the field is validated against ^[0-9]{6}$ and backup codes are 16 hexadecimal characters. They work only at login (POST /2fa/validate). If you have lost your authenticator, request an emailed code instead.
object
WebAuthn assertion, used together with challengeKey.
string
Accompanies passkeyResponse.
Whitelist the destination first. Enabling a rule (or letting it fire) is rejected server-side if destination is not on your withdrawal whitelist for currency; a paused rule can still be saved.
The withdrawal IP whitelist does not apply to auto-withdrawals — neither to managing rules on this endpoint (from any IP) nor to their scheduled execution (which has no human IP). It gates only manual withdrawals, mass payouts, and platform withdrawals. The destination wallet whitelist above is the anti-exfiltration boundary for this lifecycle.

Response

201 Created — note the status. It is 201 even when the call UPDATES an existing rule, because the endpoint is an upsert.
201 Created
The rule carries the same fields as in List rules.

Errors

These fire after the MFA factor is verified, so an emailed code is already spent when you see one. Request a fresh code before retrying.

See also