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.

POST /agents/me/settlement-rules

Create a settlement rule

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "Glossier deal",
  "currency": "USDB",
  "match": [
    {
      "creditedAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "ruleBasedAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d001",
      "counterpartyName": {
        "prefix": "GLOSSIER",
        "contains": "glossier inc"
      },
      "receivedAtWalletAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "rail": "ACH"
    }
  ],
  "splits": [
    {
      "share": {
        "basisPoints": 4000,
        "amount": 50000
      },
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      }
    }
  ],
  "priority": 1,
  "holdSeconds": 0,
  "achHoldSeconds": 86400,
  "limits": {
    "maxAmountPerExecution": 1000000,
    "maxAmountPerDay": 5000000
  }
}
'

200

{
  "id": "SettlementRule:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "name": "Glossier deal",
  "status": "PENDING_APPROVAL",
  "priority": 1,
  "currency": "USD",
  "match": [
    {
      "creditedAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "ruleBasedAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d001",
      "counterpartyName": {
        "prefix": "GLOSSIER",
        "contains": "glossier inc"
      },
      "receivedAtWalletAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
      "rail": "ACH"
    }
  ],
  "splits": [
    {
      "share": {
        "type": "PERCENT",
        "basisPoints": 4000,
        "amount": 50000
      },
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "position": 0
    }
  ],
  "holdSeconds": 0,
  "achHoldSeconds": 86400,
  "limits": {
    "maxAmountPerExecution": 1000000,
    "maxAmountPerDay": 5000000
  },
  "createdAt": "2026-11-06T18:00:00Z",
  "updatedAt": "2026-11-06T18:00:00Z",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "pendingChangeActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000098"
}

Authorizations

Authorization · string · header · required

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

Idempotency-Key · string · required

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.

Maximum string length: 255

Example:

"<uuid>"

Body

application/json

A settlement rule as an agent proposes it, for the agent's customer.

name · string · required

What the rule is called. It is the description of each payment the rule sends.

Required string length: 1 - 255

Example:

"Glossier deal"

currency · string · required

Code of the payments the rule splits, which is the currency of the Embedded Wallet its selectors name.

Example:

"USDB"

match · object[] · required

A payment matches when any selector matches it. Every selector sets creditedAccountId to the customer's Embedded Wallet.

Required array length: 1 - 20 elements

Show child attributes

splits · object[] · required

The shares, in the order they are paid. At most 20.

Minimum array length: 1

Show child attributes

priority · integer<int32>

Rules 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.

Required range: 0 <= x <= 2147483647

Example:

1

holdSeconds · integer · default: 0

How long after a payment completes the rule waits to pay it, for payments on rails other than ACH.

Required range: 0 <= x <= 86400

Example:

0

achHoldSeconds · integer · default: 86400

How long after an ACH payment completes the rule waits to pay it.

Required range: 0 <= x <= 86400

Example:

86400

limits · object

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.

Show child attributes

Response

200

application/json

The rule this Idempotency-Key already created

id · string · required

System-generated unique settlement rule identifier

Example:

"SettlementRule:019542f5-b3e7-1d02-0000-000000000001"

customerId · string · required

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

name · string · required

Example:

"Glossier deal"

status · enum<string> · required

Status of a settlement rule.

Status	Description
PENDING_APPROVAL	Proposed by an agent beyond its policy, waiting for the customer's approval. It fires on nothing.
ACTIVE	Fires on the payments it matches.
PAUSED	Fires on nothing. A payment it would have matched is tried against the customer's next rule.
DELETED	Deleted. It fires on nothing and cannot be changed.

Available options: PENDING_APPROVAL, ACTIVE, PAUSED, DELETED

priority · integer<int32> · required

Example:

1

currency · string · required

Example:

"USD"

match · object[] · required

Show child attributes

splits · object[] · required

Show child attributes

holdSeconds · integer · required

Example:

0

achHoldSeconds · integer · required

Example:

86400

limits · object · required

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.

Show child attributes

createdAt · string<date-time> · required

Example:

"2026-11-06T18:00:00Z"

updatedAt · string<date-time> · required

Example:

"2026-11-06T18:00:00Z"

agentId · string

The agent that created the rule through the agent API. Absent for a rule created with an API token.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

agentActionId · string

The CREATE_SETTLEMENT_RULE agent action awaiting the customer's approval of the rule. Present while the rule is PENDING_APPROVAL.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

pendingChangeActionId · string

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.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000098"