Create a payout run

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --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: {
    'Idempotency-Key': '<idempotency-key>',
    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', 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")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
  "status": "VALIDATING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "allOrNothing": false,
  "rowCounts": {
    "total": 1000,
    "pending": 0,
    "pendingClaim": 12,
    "processing": 0,
    "completed": 980,
    "failed": 8,
    "skipped": 0
  },
  "createdAt": "2026-11-04T22:00:00Z",
  "updatedAt": "2026-11-05T02:14:00Z",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "total": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "rowCount": 12,
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

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

Agent Operations

Create a payout run

Pay up to 50 people at once from the agent’s customer’s stablecoin Embedded Wallet, in one approved action. Each row pays a contact by phone number or email, through a claimable payout, or one of the customer’s own ACTIVE external accounts, through a send. The run pays now: there is no schedule, and rows succeed or fail one by one.

Validation is all or nothing: a row the agent may not send, or a body Grid cannot read, refuses the whole request and creates nothing. A GRID_CUSTOMER row is refused with 400. A row paying an external account the agent may not pay is refused with DESTINATION_NOT_ALLOWED.

The run is checked against the agent’s policy as one payment of total: it needs the CREATE_QUOTES and EXECUTE_QUOTES permissions, and MANAGE_EXTERNAL_ACCOUNTS when a row pays a contact; total counts toward the spending limits as one transaction, and the spending pool is charged for bank payouts. A run the policy refuses is refused with AGENT_POLICY_DENIED. A run is created PROCESSING, with an APPROVED PAYOUT_RUN agent action, when the policy runs it without approval, the spending pool does not require approval and no row is above the platform’s limit for bank payouts without approval. Otherwise it is created PENDING_APPROVAL with a PENDING_APPROVAL PAYOUT_RUN action, and the AGENT_ACTION.PENDING_APPROVAL webhook fires. Approving the action starts the run. Rejecting it, or letting it expire after 24 hours, cancels the run and skips every row.

The customer’s approval of the run covers each row’s own approval. Each row is still checked when it is paid: the destination, the agent’s delegated key, the wallet’s free balance and sanctions screening. total is what leaves the wallet; a row’s fees come out of what its recipient receives.

Available only where the platform enables payout runs and agent payout runs, and claimable payouts for runs with a contact row.

POST

agents

payout-runs

Create a payout run

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --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: {
    'Idempotency-Key': '<idempotency-key>',
    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', 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")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
  "status": "VALIDATING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "allOrNothing": false,
  "rowCounts": {
    "total": 1000,
    "pending": 0,
    "pendingClaim": 12,
    "processing": 0,
    "completed": 980,
    "failed": 8,
    "skipped": 0
  },
  "createdAt": "2026-11-04T22:00:00Z",
  "updatedAt": "2026-11-05T02:14:00Z",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "total": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "rowCount": 12,
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

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

Headers

Idempotency-Key

string

required

A unique identifier for the request, scoped to the agent. A retry with the same key and body returns the run the first request created; the same key with a different body is refused with 409.

Maximum string length: 255

Example:

"<uuid>"

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

Payout run created, or the run this Idempotency-Key already created

A payout run an agent created. allOrNothing is always false, and scheduledAt is never set.

string

required

System-generated unique payout run identifier

Example:

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

status

enum<string>

required

Status of a payout run.

Status	Description
`VALIDATING`	Grid is validating the rows. No row is paid yet.
`PENDING_APPROVAL`	An agent's run waiting for the customer to approve its `PAYOUT_RUN` action. No row is paid yet. Approving it makes the run `PROCESSING`; rejecting it, or letting it expire, makes it `CANCELLED`.
`SCHEDULED`	Accepted, waiting for `scheduledAt`.
`PROCESSING`	Rows are being paid.
`COMPLETED`	Every accepted row completed or is held for a claim, and none failed.
`PARTIALLY_FAILED`	At least one row completed or is held for a claim, and at least one failed.
`FAILED`	No row completed or is held for a claim.
`CANCELLED`	Cancelled. Rows that had not started are `SKIPPED`.

Available options:

VALIDATING,

PENDING_APPROVAL,

SCHEDULED,

PROCESSING,

COMPLETED,

PARTIALLY_FAILED,

FAILED,

CANCELLED

source

object

required

Show child attributes

allOrNothing

boolean

required

Example:

false

rowCounts

object

required

Show child attributes

createdAt

string<date-time>

required

Example:

"2026-11-04T22:00:00Z"

updatedAt

string<date-time>

required

Example:

"2026-11-05T02:14:00Z"

agentId

string

required

The agent that created the run.

Example:

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

agentActionId

string

required

The run's PAYOUT_RUN agent action, which the customer approves or rejects when the run needs approval.

Example:

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

total

object

required

The sum of the rows' amounts, in the source account's currency. This is what leaves the wallet if every row is paid.

Show child attributes

rowCount

integer

required

How many rows the run has.

Example:

12

scheduledAt

string<date-time>

When the run starts paying rows, if it was scheduled.

Example:

"2026-11-05T02:00:00Z"

finishedAt

string<date-time>

When the run reached COMPLETED, PARTIALLY_FAILED, FAILED or CANCELLED.

Example:

"2026-11-05T02:14:00Z"

Using the API

API documentation

Create a payout run

Authorizations

Headers

Body

Response