Create a settlement rule
Propose a standing split of the customer’s incoming payments into its stablecoin Embedded Wallet, paid from that wallet, as POST /settlement-rules creates one for the platform. Preview it first with POST /agents/me/settlement-rules/preview.
The wallet: every selector in match sets creditedAccountId to the customer’s stablecoin Embedded Wallet that holds this agent’s key, so the rule fires only on money landing in a wallet the agent can spend. currency is the wallet’s.
Destinations: a share pays a person by phone number or email (CONTACT), one of the customer’s own external accounts (EXTERNAL_ACCOUNT), or an Embedded Wallet on the platform (GRID_CUSTOMER). Any other destination is refused with DESTINATION_NOT_ALLOWED.
Approval: the rule is created ACTIVE when limits.maxAmountPerExecution is set and within the policy’s per-transaction limit for the wallet, limits.maxAmountPerDay is set and within its daily limit, no EXTERNAL_ACCOUNT share can exceed the platform’s limit for bank payouts without approval, and the policy sends from the wallet without approval at maxAmountPerExecution. Otherwise it is created PENDING_APPROVAL with a CREATE_SETTLEMENT_RULE agent action, named by agentActionId, and the AGENT_ACTION.PENDING_APPROVAL webhook fires. A pending rule holds its priority and fires on nothing. Approving the action makes the rule ACTIVE; rejecting it, or letting it expire after seven days, deletes it.
Priority: an omitted priority goes after the customer’s last rule that is not DELETED, the platform’s rules included.
Requires the MANAGE_SETTLEMENT_RULES permission.
Authorizations
Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.
Headers
A unique identifier for the rule, scoped to the agent. A retry with the same key and body returns the rule the first request created; the same key with a different body is rejected.
255"<uuid>"
Body
A settlement rule as an agent proposes it, for the agent's customer.
What the rule is called. It is the description of each payment the rule sends.
1 - 255"Glossier deal"
Code of the payments the rule splits, which is the currency of the Embedded Wallet its selectors name.
"USDB"
A payment matches when any selector matches it. Every selector sets creditedAccountId to the customer's Embedded Wallet.
1 - 20 elementsThe shares, in the order they are paid. At most 20.
1Rules are tried in ascending priority. Unique among the customer's rules that are not DELETED, the platform's included. Omit it to try the rule after the customer's others.
0 <= x <= 21474836471
How long after a payment completes the rule waits to pay it, for payments on rails other than ACH.
0 <= x <= 864000
How long after an ACH payment completes the rule waits to pay it.
0 <= x <= 8640086400
Caps on what the rule pays, in the smallest unit of its currency. An execution that would go over a cap is skipped with LIMIT_EXCEEDED, and the customer keeps the payment.
Response
The rule this Idempotency-Key already created
System-generated unique settlement rule identifier
"SettlementRule:019542f5-b3e7-1d02-0000-000000000001"
"Customer:019542f5-b3e7-1d02-0000-000000000001"
"Glossier deal"
Status of a settlement rule.
PENDING_APPROVAL, ACTIVE, PAUSED, DELETED 1
"USD"
0
86400
Caps on what the rule pays, in the smallest unit of its currency. An execution that would go over a cap is skipped with LIMIT_EXCEEDED, and the customer keeps the payment.
"2026-11-06T18:00:00Z"
"2026-11-06T18:00:00Z"
The agent that created the rule through the agent API. Absent for a rule created with an API token.
"Agent:019542f5-b3e7-1d02-0000-000000000042"
The CREATE_SETTLEMENT_RULE agent action awaiting the customer's approval of the rule. Present while the rule is PENDING_APPROVAL.
"AgentAction:019542f5-b3e7-1d02-0000-000000000099"
The UPDATE_SETTLEMENT_RULE agent action holding a change to the rule's match, shares or limits until the customer approves it. Present while the change waits; the rule keeps its current terms until then.
"AgentAction:019542f5-b3e7-1d02-0000-000000000098"