List agent transaction approval requests

Retrieve a paginated list of agent actions that require platform approval. Filter by agentId or customerId to scope results to a specific agent or customer. Approve or reject individual actions via POST /agents/{agentId}/actions/{actionId}/approve or POST /agents/{agentId}/actions/{actionId}/reject.

GET /agents/approvals

List agent transaction approval requests

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/agents/approvals \
  --header 'Authorization: Basic <encoded-value>'

200

{
  "data": [
    {
      "id": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
      "platformCustomerId": "user-a1b2c3",
      "status": "PENDING_APPROVAL",
      "type": "EXECUTE_QUOTE",
      "expiresAt": "2025-10-03T15:05:00Z",
      "createdAt": "2025-10-03T15:00:00Z",
      "updatedAt": "2025-10-03T15:02:00Z",
      "quote": {
        "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
        "status": "PENDING",
        "createdAt": "2025-10-03T12:00:00Z",
        "expiresAt": "2025-10-03T12:05:00Z",
        "source": {
          "sourceType": "ACCOUNT",
          "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
          "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
        },
        "destination": {
          "destinationType": "ACCOUNT",
          "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
          "paymentRail": "ACH"
        },
        "sendingCurrency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        },
        "receivingCurrency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        },
        "totalSendingAmount": 123010,
        "totalReceivingAmount": 1000,
        "exchangeRate": 123,
        "feesIncluded": 10,
        "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
        "platformFeesIncluded": 5,
        "paymentInstructions": [
          {
            "accountOrWalletInfo": {
              "accountType": "USD_ACCOUNT",
              "paymentRails": [
                "ACH",
                "WIRE"
              ],
              "accountNumber": "1234567890",
              "routingNumber": "021000021",
              "bankName": "Chase Bank",
              "reference": "UMA-Q12345-REF"
            },
            "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
          },
          {
            "accountOrWalletInfo": {
              "accountType": "SPARK_WALLET",
              "assetType": "BTC",
              "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
              "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
            }
          }
        ],
        "counterpartyInformation": {
          "FULL_NAME": "John Sender",
          "BIRTH_DATE": "1985-06-15",
          "NATIONALITY": "DE"
        },
        "rateDetails": {
          "counterpartyMultiplier": 1.08,
          "counterpartyFixedFee": 10,
          "gridApiMultiplier": 0.925,
          "gridApiFixedFee": 10,
          "gridApiVariableFeeRate": 0.003,
          "gridApiVariableFeeAmount": 30
        },
        "purposeOfPayment": "GIFT",
        "documentIds": [
          "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
          "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
          "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
        ],
        "scaChallenge": {
          "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
          "expiresAt": "2025-10-03T12:05:00Z",
          "factor": "SMS_OTP",
          "availableFactors": [
            "SMS_OTP"
          ],
          "purpose": "PAYOUT",
          "passkeyAssertionOptions": {},
          "passkeyAllowedOrigins": [
            "https://app.example.com"
          ]
        },
        "minimumReceivingAmount": 1000,
        "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
        "destinationChainAddress": {
          "destinationType": "CHAIN_ADDRESS",
          "network": "BASE",
          "currency": "USDC",
          "address": "0x1234567890abcdef1234567890abcdef12345678"
        },
        "destinationLightningInvoice": {
          "destinationType": "LIGHTNING_INVOICE",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      },
      "previousQuote": {
        "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
        "status": "PENDING",
        "createdAt": "2025-10-03T12:00:00Z",
        "expiresAt": "2025-10-03T12:05:00Z",
        "source": {
          "sourceType": "ACCOUNT",
          "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
          "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
        },
        "destination": {
          "destinationType": "ACCOUNT",
          "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
          "paymentRail": "ACH"
        },
        "sendingCurrency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        },
        "receivingCurrency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        },
        "totalSendingAmount": 123010,
        "totalReceivingAmount": 1000,
        "exchangeRate": 123,
        "feesIncluded": 10,
        "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
        "platformFeesIncluded": 5,
        "paymentInstructions": [
          {
            "accountOrWalletInfo": {
              "accountType": "USD_ACCOUNT",
              "paymentRails": [
                "ACH",
                "WIRE"
              ],
              "accountNumber": "1234567890",
              "routingNumber": "021000021",
              "bankName": "Chase Bank",
              "reference": "UMA-Q12345-REF"
            },
            "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
          },
          {
            "accountOrWalletInfo": {
              "accountType": "SPARK_WALLET",
              "assetType": "BTC",
              "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
              "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
            }
          }
        ],
        "counterpartyInformation": {
          "FULL_NAME": "John Sender",
          "BIRTH_DATE": "1985-06-15",
          "NATIONALITY": "DE"
        },
        "rateDetails": {
          "counterpartyMultiplier": 1.08,
          "counterpartyFixedFee": 10,
          "gridApiMultiplier": 0.925,
          "gridApiFixedFee": 10,
          "gridApiVariableFeeRate": 0.003,
          "gridApiVariableFeeAmount": 30
        },
        "purposeOfPayment": "GIFT",
        "documentIds": [
          "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
          "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
          "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
        ],
        "scaChallenge": {
          "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
          "expiresAt": "2025-10-03T12:05:00Z",
          "factor": "SMS_OTP",
          "availableFactors": [
            "SMS_OTP"
          ],
          "purpose": "PAYOUT",
          "passkeyAssertionOptions": {},
          "passkeyAllowedOrigins": [
            "https://app.example.com"
          ]
        },
        "minimumReceivingAmount": 1000,
        "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
        "destinationChainAddress": {
          "destinationType": "CHAIN_ADDRESS",
          "network": "BASE",
          "currency": "USDC",
          "address": "0x1234567890abcdef1234567890abcdef12345678"
        },
        "destinationLightningInvoice": {
          "destinationType": "LIGHTNING_INVOICE",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      },
      "priceTolerance": {
        "basisPoints": 100,
        "minimumAmount": 100,
        "currency": "USD"
      },
      "purchaseCard": {
        "amount": 4999,
        "spendLimit": 5749,
        "currency": "USD",
        "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
        "increaseCardId": "Card:019542f5-b3e7-1d02-0000-000000000011",
        "previousAmount": 4999,
        "previousSpendLimit": 5749,
        "description": "Running shoes from example-store.com",
        "recurring": false,
        "expiresAt": "2026-10-26T15:30:00Z"
      },
      "claimablePayout": {
        "id": "ClaimablePayout:019542f5-b3e7-1d02-0000-000000000077",
        "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
        "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
        "platformCustomerId": "user-a1b2c3",
        "status": "PENDING_APPROVAL",
        "sourceAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
        "amount": {
          "amount": 12550,
          "currency": {
            "code": "USD",
            "name": "United States Dollar",
            "symbol": "$",
            "decimals": 2
          }
        },
        "recipient": {
          "name": "Maria",
          "phoneNumber": "[phone]",
          "email": "[e-mail]",
          "country": "PH"
        },
        "expiresAt": "2025-10-10T15:00:00Z",
        "createdAt": "2025-10-03T15:00:00Z",
        "updatedAt": "2025-10-03T15:02:00Z",
        "note": "Happy birthday, Mom",
        "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
        "externalAccountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
        "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
        "receivedAmount": {
          "amount": 12550,
          "currency": {
            "code": "USD",
            "name": "United States Dollar",
            "symbol": "$",
            "decimals": 2
          }
        },
        "paymentRail": "ACH",
        "failureReason": "INSUFFICIENT_FUNDS"
      },
      "storedCardUse": {
        "storedCardId": "StoredCard:019542f5-b3e7-1d02-0000-000000000077",
        "card": {
          "lastFour": "0005",
          "brand": "VISA",
          "funding": "CREDIT",
          "expiryMonth": 8,
          "expiryYear": 2029,
          "issuerCountry": "US",
          "nickname": "Personal Visa"
        },
        "merchant": "example-store.com",
        "amount": 4999,
        "currency": "USD",
        "purpose": "Running shoes, size 10",
        "needsCvc": false,
        "autoApproved": false,
        "linkIssuedAt": "2026-11-06T15:00:30Z",
        "revealedAt": "2026-11-06T15:00:41Z"
      },
      "settlementRule": {
        "id": "SettlementRule:019542f5-b3e7-1d02-0000-000000000001",
        "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
        "name": "Glossier deal",
        "status": "PENDING_APPROVAL",
        "priority": 1,
        "currency": "USD",
        "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": {
              "type": "PERCENT",
              "basisPoints": 4000,
              "amount": 50000
            },
            "destination": {
              "destinationType": "EXTERNAL_ACCOUNT",
              "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
            },
            "position": 0
          }
        ],
        "holdSeconds": 0,
        "achHoldSeconds": 86400,
        "limits": {
          "maxAmountPerExecution": 1000000,
          "maxAmountPerDay": 5000000
        },
        "createdAt": "2026-11-06T18:00:00Z",
        "updatedAt": "2026-11-06T18:00:00Z",
        "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
        "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
        "pendingChangeActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000098"
      },
      "payoutRun": {
        "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
        "status": "VALIDATING",
        "sourceAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
        "total": {
          "amount": 12550,
          "currency": {
            "code": "USD",
            "name": "United States Dollar",
            "symbol": "$",
            "decimals": 2
          }
        },
        "rowCount": 12,
        "rows": [
          {
            "clientRowId": "contractor-0042",
            "amount": 25000000,
            "destination": {
              "destinationType": "EXTERNAL_ACCOUNT",
              "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
            },
            "description": "October invoice"
          }
        ]
      },
      "cardId": "Card:019542f5-b3e7-1d02-0000-000000000011",
      "transaction": {
        "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
        "status": "CREATED",
        "type": "INCOMING",
        "direction": "CREDIT",
        "destination": {
          "destinationType": "ACCOUNT",
          "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
          "currency": "EUR",
          "railDetails": {
            "paymentRail": "ONCHAIN",
            "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
            "network": "SOLANA"
          },
          "onChainTransaction": {
            "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
            "network": "SOLANA"
          }
        },
        "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
        "platformCustomerId": "18d3e5f7b4a9c2",
        "pendingReason": "COUNTERPARTY_DECLARATION_REQUIRED",
        "ruleBasedAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000011",
        "settledAt": "2025-08-15T14:30:00Z",
        "createdAt": "2025-08-15T14:25:18Z",
        "updatedAt": "2025-08-15T14:30:00Z",
        "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z",
        "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
        "description": "Payment for invoice #1234",
        "sentAmount": {
          "amount": 12550,
          "currency": {
            "code": "USD",
            "name": "United States Dollar",
            "symbol": "$",
            "decimals": 2
          }
        },
        "exchangeRate": 1.08,
        "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
        "refund": {
          "reference": "UMA-Q12345-REFUND",
          "initiatedAt": "2025-08-15T14:30:00Z",
          "status": "COMPLETED",
          "settledAt": "2025-08-15T14:35:00Z",
          "reason": "TRANSACTION_FAILED"
        },
        "counterpartyInformation": {
          "FULL_NAME": "John Sender",
          "BIRTH_DATE": "1985-06-15",
          "NATIONALITY": "DE"
        },
        "source": {
          "sourceType": "ACCOUNT",
          "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
          "currency": "USD",
          "railDetails": {
            "paymentRail": "ONCHAIN",
            "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
            "network": "SOLANA"
          },
          "onChainTransaction": {
            "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
            "network": "SOLANA"
          }
        },
        "receivedAmount": {
          "amount": 12550,
          "currency": {
            "code": "USD",
            "name": "United States Dollar",
            "symbol": "$",
            "decimals": 2
          }
        },
        "fees": 10,
        "reconciliationInstructions": {
          "reference": "UMA-Q12345-REF",
          "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
        },
        "failureReason": "LNURLP_FAILED"
      },
      "rejectionReason": "Transaction amount exceeds customer's current risk limit.",
      "failureReason": "QUOTE_EXPIRED"
    }
  ],
  "hasMore": true,
  "nextCursor": "<string>",
  "totalCount": 123
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Query Parameters

agentId · string

Filter by agent ID

customerId · string

Filter by customer ID

startDate · string<date-time>

Filter by start date (inclusive) in ISO 8601 format

endDate · string<date-time>

Filter by end date (inclusive) in ISO 8601 format

limit · integer · default: 20

Maximum number of results to return (default 20, max 100)

Required range: 1 <= x <= 100

cursor · string

Cursor for pagination (returned from previous request)

sortOrder · enum<string> · default: desc

Order to sort results in

Available options: asc, desc

Response

200

application/json

Successful operation

data · object[] · required

List of agent actions matching the filter criteria.

Show child attributes

hasMore · boolean · required

Indicates if more results are available beyond this page.

nextCursor · string

Cursor to retrieve the next page of results (only present if hasMore is true).

totalCount · integer

Total number of actions matching the criteria (excluding pagination).