Preview a settlement rule

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
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"currency\": \"USDB\",\n  \"match\": [\n    {\n      \"creditedAccountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n      \"ruleBasedAccountId\": \"InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d001\",\n      \"counterpartyName\": {\n        \"prefix\": \"GLOSSIER\",\n        \"contains\": \"glossier inc\"\n      },\n      \"receivedAtWalletAddress\": \"spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu\",\n      \"rail\": \"ACH\"\n    }\n  ],\n  \"splits\": [\n    {\n      \"share\": {\n        \"basisPoints\": 4000,\n        \"amount\": 50000\n      },\n      \"destination\": {\n        \"destinationType\": \"EXTERNAL_ACCOUNT\",\n        \"externalAccountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\"\n      }\n    }\n  ],\n  \"amount\": 1000000\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/preview")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Agent Operations

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

settlement-rules

preview

Preview a settlement rule

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
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"currency\": \"USDB\",\n  \"match\": [\n    {\n      \"creditedAccountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n      \"ruleBasedAccountId\": \"InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d001\",\n      \"counterpartyName\": {\n        \"prefix\": \"GLOSSIER\",\n        \"contains\": \"glossier inc\"\n      },\n      \"receivedAtWalletAddress\": \"spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu\",\n      \"rail\": \"ACH\"\n    }\n  ],\n  \"splits\": [\n    {\n      \"share\": {\n        \"basisPoints\": 4000,\n        \"amount\": 50000\n      },\n      \"destination\": {\n        \"destinationType\": \"EXTERNAL_ACCOUNT\",\n        \"externalAccountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\"\n      }\n    }\n  ],\n  \"amount\": 1000000\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/settlement-rules/preview")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

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

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

Using the API

API documentation

Preview a settlement rule

Authorizations

Body

Response