Preview a payout run

What POST /agents/me/payout-runs would do with this body, without doing any of it: nothing is created, held, reserved or quoted. The body is checked as a create checks it, so a body the create would refuse is refused here with the same error.

The answer gives total, which is what leaves the wallet, the wallet’s free balance after it, and whether the run would wait for the customer’s approval and why. When the agent’s policy would refuse the run, denialReason says which rule. Each row’s fee is an estimate where Grid knows it: a contact row’s fee depends on the account the recipient claims to, so it is set at the claim.

POST /agents/me/payout-runs/preview

Preview a payout run

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "rows": [
    {
      "clientRowId": "contractor-0042",
      "amount": 25000000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "description": "October invoice"
    }
  ]
}
'

200

{
  "sourceAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "total": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "walletBalanceAfter": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "rows": [
    {
      "clientRowId": "contractor-0042",
      "amount": {
        "amount": 12550,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      },
      "feeSetAtClaim": true,
      "estimatedFee": {
        "amount": 12550,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      },
      "estimatedReceiveAmount": {
        "amount": 12550,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      }
    }
  ],
  "approval": {
    "required": true,
    "reasons": [
      "APPROVAL_MODE"
    ]
  },
  "estimatedFees": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "denialReason": "DAILY_LIMIT_EXCEEDED"
}

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

sourceAccountId · string · required

The customer's stablecoin Embedded Wallet that pays every row. It must hold an ACTIVE delegated key of this agent.

Example:

"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

rows · object[] · required

The people to pay. Each pays a CONTACT or an EXTERNAL_ACCOUNT: one of the customer's own ACTIVE external accounts on the platform. A GRID_CUSTOMER row is refused.

Required array length: 1 - 50 elements

Show child attributes

Response

200

application/json

The run as it would be created

sourceAccountId · string · required

Example:

"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

total · object · required

The sum of the rows' amounts, which is what leaves the wallet if every row is paid. Fees are not added to it.

Show child attributes

walletBalanceAfter · object · required

The wallet's free balance, after what is already held for its claimable payouts and payments in flight, minus total. Negative when the wallet cannot pay every row.

Show child attributes

rows · object[] · required

Show child attributes

approval · object · required

Show child attributes

estimatedFees · object

The sum of the rows' known fee estimates. Absent when no row's fee is known.

Show child attributes

denialReason · string

Set when the agent's policy or spending pool would refuse the run, so the create would be refused with AGENT_POLICY_DENIED.

Example:

"DAILY_LIMIT_EXCEEDED"