Preview a payout run

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

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

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/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  \"sourceAccountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n  \"rows\": [\n    {\n      \"clientRowId\": \"contractor-0042\",\n      \"amount\": 25000000,\n      \"destination\": {\n        \"destinationType\": \"EXTERNAL_ACCOUNT\",\n        \"externalAccountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\"\n      },\n      \"description\": \"October invoice\"\n    }\n  ]\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/preview")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

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

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

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

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

Agent Operations

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

payout-runs

preview

Preview a payout run

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

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

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/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  \"sourceAccountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n  \"rows\": [\n    {\n      \"clientRowId\": \"contractor-0042\",\n      \"amount\": 25000000,\n      \"destination\": {\n        \"destinationType\": \"EXTERNAL_ACCOUNT\",\n        \"externalAccountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\"\n      },\n      \"description\": \"October invoice\"\n    }\n  ]\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/preview")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

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

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

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

{
  "code": "SERVICE_UNAVAILABLE",
  "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

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

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"

Using the API

API documentation

Preview a payout run

Authorizations

Body

Response