Approve an agent action

Approve a pending agent action, allowing Grid to proceed with execution. The action must have status PENDING_APPROVAL. Once approved, Grid executes the underlying operation (quote execution or transfer) and the action transitions to APPROVED. For EXECUTE_QUOTE actions, note that the underlying quote may have expired between submission and approval — in that case the action will transition to FAILED instead. This endpoint is called by the platform’s backend using platform credentials, not by the agent itself.

POST /agents/{agentId}/actions/{actionId}/approve

cURL

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/actions/{actionId}/approve \
  --header 'Authorization: Basic <encoded-value>'

200

{
  "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",
  "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",
    "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
    }
  },
  "transferDetails": {
    "amount": 50000,
    "currency": "USD",
    "sourceAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "destinationAccountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
  },
  "transaction": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
    "status": "CREATED",
    "type": "INCOMING",
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "currency": "EUR"
    },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "18d3e5f7b4a9c2",
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "settledAt": "2025-08-15T14:30:00Z",
    "createdAt": "2025-08-15T14:25:18Z",
    "updatedAt": "2025-08-15T14:30:00Z",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "description": "Payment for invoice #1234",
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "currency": "USD"
    },
    "reconciliationInstructions": {
      "reference": "UMA-Q12345-REF"
    },
    "rateDetails": {
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    },
    "failureReason": "LNURLP_FAILED"
  },
  "rejectionReason": "Transaction amount exceeds customer's current risk limit."
}

Authorizations

Authorization · string · header · required

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

Path Parameters

agentId · string · required

System-generated unique agent identifier

actionId · string · required

Unique identifier of the agent action to approve

Response

200

application/json

Action approved successfully. Returns the updated AgentAction.

An action submitted by an agent that may require platform approval before execution. All agent-initiated operations (quote execution, transfers) are represented as AgentActions, giving the platform a consistent object to approve, reject, and audit regardless of the underlying operation type.

id · string · required

System-generated unique identifier for this action.

Example:

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

agentId · string · required

The agent that submitted this action.

Example:

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

customerId · string · required

The customer on whose behalf the action was submitted.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000010"

platformCustomerId · string · required

Platform-specific ID of the customer.

Example:

"user-a1b2c3"

status · enum<string> · required

Status of an agent action.

Status	Description
PENDING_APPROVAL	Submitted by the agent, awaiting platform approval before execution
APPROVED	Approved by the platform; execution is in progress or completed
REJECTED	Rejected by the platform; the underlying transaction was not executed
FAILED	Approved but execution failed (e.g. quote expired, insufficient funds)

Available options: PENDING_APPROVAL, APPROVED, REJECTED, FAILED

type · enum<string> · required

The type of action the agent is requesting.

Type	Description
EXECUTE_QUOTE	Execute a cross-currency quote
TRANSFER_OUT	Transfer from an internal account to an external account
TRANSFER_IN	Transfer from an external account to an internal account

Available options: EXECUTE_QUOTE, TRANSFER_OUT, TRANSFER_IN

createdAt · string<date-time> · required

When the action was submitted by the agent.

Example:

"2025-10-03T15:00:00Z"

updatedAt · string<date-time> · required

When the action was last updated.

Example:

"2025-10-03T15:02:00Z"

quote · object

The quote being executed. Populated for EXECUTE_QUOTE actions; absent for transfer actions. Contains the full amount, currency, destination, and rate details needed to present an approval decision to the user.

Show child attributes

transferDetails · object

Details of the transfer being requested. Populated for TRANSFER_OUT and TRANSFER_IN actions; absent for EXECUTE_QUOTE actions.

Show child attributes

transaction · Incoming Transaction · object

The resulting transaction, populated once the action has been approved and execution has begun. Absent while the action is PENDING_APPROVAL or REJECTED.

Incoming Transaction

Outgoing Transaction

Show child attributes

rejectionReason · string

Human-readable reason provided by the platform when rejecting the action. Only present when status is REJECTED.

Example:

"Transaction amount exceeds customer's current risk limit."