Preview a settlement rule

What a rule the agent drafts would pay on a payment of amount, and which of the customer’s recent payments it would have fired on, as POST /settlement-rules/preview answers for a draft. Nothing is created or paid. The body is the draft’s fields and amount, with no customerId: the rule is for the agent’s customer.

The draft is checked as POST /agents/me/settlement-rules checks a rule, so a draft the agent could not create is refused here first: every selector’s creditedAccountId is the customer’s stablecoin Embedded Wallet that holds this agent’s key, currency is the wallet’s, and every share pays a destination an agent may pay, or the preview is refused with DESTINATION_NOT_ALLOWED.

Requires the MANAGE_SETTLEMENT_RULES permission.

POST /agents/me/settlement-rules/preview

Preview a settlement rule

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
      }
    }
  ],
  "amount": 1000000
}
'

200

{
  "currency": "USD",
  "amount": 1000000,
  "splits": [
    {
      "position": 0,
      "share": {
        "type": "PERCENT",
        "basisPoints": 4000,
        "amount": 50000
      },
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "amount": 400000
    }
  ],
  "ownerKeeps": 450000,
  "recentMatches": [
    {
      "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
      "amount": 1000000,
      "currency": "USD",
      "completedAt": "2026-11-06T18:00:00Z",
      "counterpartyName": "GLOSSIER INC"
    }
  ],
  "skipReason": "RULE_PAUSED"
}

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.

Body

application/json

A draft rule and a payment to split by it. The draft's fields sit at the top level, beside amount.

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

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

amount · integer<int64> · required

A payment to split, in the smallest unit of the draft's currency.

Required range: 1 <= x <= 9000000000000000

Example:

1000000

Response

200

application/json

The preview

currency · string · required

Example:

"USD"

amount · integer<int64> · required

The payment previewed.

Example:

1000000

splits · object[] · required

Every row of the rule, in row order.

Show child attributes

ownerKeeps · integer<int64> · required

What stays with the customer.

Example:

450000

recentMatches · object[] · required

Show child attributes

skipReason · enum<string>

Why an execution paid nothing.

Reason	Description
RULE_PAUSED	The rule was paused before the execution fired.
INCOMING_PAYMENT_RETURNED	The payment was returned before the execution fired.
AMOUNT_BELOW_RULE	The payment was smaller than the fixed and percentage shares together.
LIMIT_EXCEEDED	Paying it would have gone over one of the rule's limits.
CANCELLED	The execution was cancelled, or the rule deleted, while it was held.
CREATOR_REVOKED	The API token or agent that created the rule can no longer send payments. The rule is paused.
AGENT_PAUSED	The agent that created the rule is paused. The rule stays active, and pays the next payment once the agent is resumed.

Available options: RULE_PAUSED, INCOMING_PAYMENT_RETURNED, AMOUNT_BELOW_RULE, LIMIT_EXCEEDED, CANCELLED, CREATOR_REVOKED, AGENT_PAUSED