Guides

Automation Policies

Rules that allow, review or block operations, evaluated through the API.

Automation Policies are rules you define in the Hub (Settings, then Policies) to control what your users can do: spending limits, blocked countries, a maturation delay before withdrawals, and automatic conversion or sweep of balances. Your application asks the API for a decision before it acts, then applies it.

Note Policies never execute anything. The API returns a decision and, when relevant, effects described as data. Your application is responsible for applying them.

Rule types#

Type	Parameters	Possible actions
`max_per_transaction`	`amount`, `currency`, optional `operations`	`block`, `review`
`max_per_day`, `max_per_month`	`amount`, `currency`, optional `operations`. Totals are per user and per currency, in UTC.	`block`, `review`
`max_withdrawal`	`amount`, `currency`	`block`, `review`
`withdrawal_maturation`	`days` (1 to 365), counted from the user's last deposit	`block`, `review`
`blocked_countries`	`countries` (ISO 3166-1 alpha-2)	`block`, `review`
`auto_convert_deposit`	`fromCurrency` (EUR or USD), optional `minAmount`	`apply`
`auto_withdraw_threshold`	`thresholdUsd`	`apply`

A limit is exceeded when the amount (plus the running total) is strictly greater than the cap: reaching it exactly is allowed. operations is any of deposit, withdrawal, payment, transfer (all by default). Rules are evaluated in the order of your list.

Decisions#

All enabled rules are evaluated, so the response lists every rule that matched. The decision is the strictest one: block beats review, which beats allow.

Decision	Meaning
`allow`	No rule objected. Proceed.
`review`	At least one rule asks for a human check. Hold the operation.
`block`	At least one rule forbids it. Refuse the operation.

Effects are produced only when the decision is not block: convert_to_usdc (an automatic conversion of a deposit) and sweep_to_company_account (a balance above your threshold should be swept).

Evaluate an operation#

Evaluate Automation Policies with the operation you are about to perform. When you pass user_id, daily and monthly totals and the date of the last deposit are read from the user's history; otherwise provide balance_usd yourself for sweep rules.

curl -X POST "https://sdk.tilt-pay.com/v1/policies/evaluate" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1c0d36-5f0e-4d2a-9a43-0b8c6e2f1a90" \
  -d '{"user_id": "4821", "operation": "withdrawal", "amount": 250, "currency": "USD", "country": "FR"}'

JSON

{
  "decision": "review",
  "matched_rules": [
    { "rule_id": "7a1f…", "type": "withdrawal_maturation", "action": "review", "reason": "Last deposit was 2 days ago (minimum 7)" }
  ],
  "effects": []
}

Every evaluation made through the API is logged in the Hub, where you can also simulate rules before saving them. Users that belong to no project are never concerned.