Agent Operations

Execute a quote

Changed on Nov 2, 2026

Execute a quote created by the authenticated agent. Requires the EXECUTE_QUOTES permission in the agent's policy. When the source is an EMBEDDED_WALLET, Grid signs with the agent's active delegated key for that wallet. If the agent's policy requires approval for this amount (based on execution mode or approval thresholds), the transaction will be created in a pending state and must be approved by the platform via POST /agents/{agentId}/actions/{actionId}/approve. The action expires when its quote expires, and approval after expiry fails the action, unless the action has priceTolerance: it then waits for approval until its own expiresAt. Approved while its quote is live, it executes that quote; approved after the quote expired, Grid quotes the send again (see POST /agents/{agentId}/actions/{actionId}/approve). A retry with the first quote's id still returns the action after approval replaced its quote. Once executed, the quote cannot be cancelled.

post/agents/me/quotes/{quoteId}/execute

Request

Base URL
https://api.lightspark.com/grid/2025-10-13
URL
https://api.lightspark.com/grid/2025-10-13/agents/me/quotes/{quoteId}/execute
Auth
HTTP bearer

Headers

Idempotency-Keystring

Example:<uuid>

A unique identifier for the request. If the same key is sent multiple times, the server will return the same response as the first request.

Response

Action submitted successfully. If the agent's policy requires approval, the returned AgentAction will have status PENDING_APPROVAL and no transaction yet. If the policy permits automatic execution, status will be APPROVED and transaction will be populated. Note: if approval is required, the underlying quote may expire before the platform approves. Without priceTolerance, the action then transitions to FAILED; with it, approval quotes the send again.

idstring required

System-generated unique identifier for this action.

agentIdstring required

The agent that submitted this action.

customerIdstring required

The customer on whose behalf the action was submitted.

platformCustomerIdstring required

Platform-specific ID of the customer.

status'PENDING_APPROVAL' | 'APPROVED' | 'REJECTED' | 'FAILED' 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	Not executed, or execution failed; see failureReason

type'EXECUTE_QUOTE' | 'ISSUE_PURCHASE_CARD' required

The type of action the agent is requesting.

Type	Description
EXECUTE_QUOTE	Execute a quote
ISSUE_PURCHASE_CARD	Issue a purchase card: single-use, or recurring when purchaseCard.recurring is true. See purchaseCard

cardIdstring

The purchase card the action issued. Present for an ISSUE_PURCHASE_CARD action once it is APPROVED and the card is issued; read it with GET /agents/me/cards/{cardId}.

rejectionReasonstring

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

Why an agent action has status FAILED.

Reason	Description
QUOTE_EXPIRED	The action's quote expired before execution, or, for an action Grid quotes again on approval, Grid could no longer quote the send
POLICY_DENIED	The agent policy no longer allowed the action
AGENT_INACTIVE	The agent was paused or deleted before execution
EXECUTION_FAILED	Grid could not execute the approved action. For ISSUE_PURCHASE_CARD, the card issuer did not issue the card
PRICE_MOVED	Reserved and legacy. Quotes to a CHAIN_ADDRESS pay out at a locked rate and no longer fail with this reason
ADDRESS_REFUSED	Grid refused the send's destination before it signed the send: the destination is no longer one the agent may send to (for example, a Spark address removed from the customer's saved addresses), or one of the customer's records of the address was refused or is held for review. A CHAIN_ADDRESS that screening refuses fails with EXECUTION_FAILED
APPROVAL_EXPIRED	An ISSUE_PURCHASE_CARD action, or an EXECUTE_QUOTE action with priceTolerance, was not approved before its expiresAt

expiresAtstring date-time required

When the action expires. For an EXECUTE_QUOTE action with priceTolerance, this is the end of the platform's approval window, independent of the quote's own expiry: approval executes a live quote and quotes the send again once it has expired, and a pending action that reaches this time fails with APPROVAL_EXPIRED. For any other EXECUTE_QUOTE action, this is the quote's own expiry; a pending action that reaches it fails with QUOTE_EXPIRED, and approval never creates a replacement quote. For ISSUE_PURCHASE_CARD, this is the end of the approval window, after which a pending action fails with APPROVAL_EXPIRED.

createdAtstring date-time required

When the action was submitted by the agent.

updatedAtstring date-time required

When the action was last updated.

Example response

{
  "id": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "platformCustomerId": "user-a1b2c3",
  "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,
    "feesIncluded": 10,
    "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"
        }
      }
    ],
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "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
    },
    "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",
      "availableFactors": [
        "SMS_OTP"
      ],
      "purpose": "PAYOUT",
      "passkeyAllowedOrigins": [
        "https://app.example.com"
      ]
    },
    "minimumReceivingAmount": 1000,
    "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
    "destinationChainAddress": {
      "destinationType": "CHAIN_ADDRESS",
      "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,
    "feesIncluded": 10,
    "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"
        }
      }
    ],
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "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
    },
    "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",
      "availableFactors": [
        "SMS_OTP"
      ],
      "purpose": "PAYOUT",
      "passkeyAllowedOrigins": [
        "https://app.example.com"
      ]
    },
    "minimumReceivingAmount": 1000,
    "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
    "destinationChainAddress": {
      "destinationType": "CHAIN_ADDRESS",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "destinationLightningInvoice": {
      "destinationType": "LIGHTNING_INVOICE",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  },
  "priceTolerance": {
    "basisPoints": 100,
    "minimumAmount": 100,
    "currency": "USD"
  },
  "purchaseCard": {
    "amount": 4999,
    "spendLimit": 5749,
    "currency": "USD",
    "description": "Running shoes from example-store.com",
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "expiresAt": "2026-10-26T15:30:00Z"
  },
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000011",
  "transaction": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
    "destination": {
      "destinationType": "ACCOUNT",
      "currency": "EUR",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "railDetails": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      },
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "ruleBasedAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000011",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "18d3e5f7b4a9c2",
    "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",
      "settledAt": "2025-08-15T14:35:00Z",
      "status": "COMPLETED",
      "reason": "TRANSACTION_FAILED"
    },
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "source": {
      "sourceType": "ACCOUNT",
      "currency": "USD",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "railDetails": {
        "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"
    }
  },
  "rejectionReason": "Transaction amount exceeds customer's current risk limit.",
  "expiresAt": "2025-10-03T15:05:00Z",
  "createdAt": "2025-10-03T15:00:00Z",
  "updatedAt": "2025-10-03T15:02:00Z"
}

Changes

Nov 2, 2026f90f21cf21e8 Revision changes
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
Nov 2, 2026e3a3f79a161f Revision changes
- info
  added the optional property / to the response with the status

Operation history (27 revisions)