Execute a quote

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/quotes/{quoteId}/execute \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/quotes/{quoteId}/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/quotes/{quoteId}/execute")
  .post(null)
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

{
  "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": 990000
  },
  "purchaseCard": {
    "kind": "SINGLE_USE",
    "currency": "USD",
    "amount": 2000,
    "sourceAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "memo": "Concert tickets"
  },
  "card": {
    "card": {
      "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "status": "PENDING_KYC",
      "form": "VIRTUAL",
      "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
      "maxSpendPerTransaction": 5000,
      "maxSpendPerDay": 25000,
      "maxTransactionsPerDay": 20,
      "createdAt": "2026-05-08T14:10:00Z",
      "updatedAt": "2026-05-08T14:11:00Z",
      "platformCardId": "card-emp-001",
      "statusReason": "DELEGATION_REQUIRED",
      "brand": "VISA",
      "pinStatus": "OK",
      "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2029,
      "cardCapabilities": {
        "supportsSpendLimits": true,
        "supportsSpendLimitsAtIssuance": true,
        "supportsTransactionCountLimit": true,
        "supports3dSecurePassword": false,
        "supportsPanReveal": true,
        "supportsDigitalWalletTokenization": true
      },
      "allowedMccs": [
        "5411"
      ],
      "blockedMccs": [
        "7995"
      ],
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "defaultMccBlocksLifted": false,
      "currency": "USD",
      "processorRef": "card_b81c2a4f",
      "issuerRef": "lead_card_7a1b9c3d"
    },
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "agentCardKind": "STANDARD",
    "effectiveBlockedMccs": [
      "7995",
      "6051"
    ],
    "spendLimit": {
      "amount": 2300,
      "duration": "TRANSACTION"
    },
    "reservedAmount": 2300,
    "expiresAt": "2026-10-10T15:30:00Z"
  },
  "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"
}

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

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

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

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

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

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

Agent Operations

Execute a quote

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. Approval after expiry fails the action; Grid does not create a replacement quote. Once executed, the quote cannot be cancelled.

POST

agents

quotes

{quoteId}

execute

Execute a quote

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/quotes/{quoteId}/execute \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/quotes/{quoteId}/execute', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/quotes/{quoteId}/execute")
  .post(null)
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

{
  "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": 990000
  },
  "purchaseCard": {
    "kind": "SINGLE_USE",
    "currency": "USD",
    "amount": 2000,
    "sourceAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "memo": "Concert tickets"
  },
  "card": {
    "card": {
      "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "status": "PENDING_KYC",
      "form": "VIRTUAL",
      "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
      "maxSpendPerTransaction": 5000,
      "maxSpendPerDay": 25000,
      "maxTransactionsPerDay": 20,
      "createdAt": "2026-05-08T14:10:00Z",
      "updatedAt": "2026-05-08T14:11:00Z",
      "platformCardId": "card-emp-001",
      "statusReason": "DELEGATION_REQUIRED",
      "brand": "VISA",
      "pinStatus": "OK",
      "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2029,
      "cardCapabilities": {
        "supportsSpendLimits": true,
        "supportsSpendLimitsAtIssuance": true,
        "supportsTransactionCountLimit": true,
        "supports3dSecurePassword": false,
        "supportsPanReveal": true,
        "supportsDigitalWalletTokenization": true
      },
      "allowedMccs": [
        "5411"
      ],
      "blockedMccs": [
        "7995"
      ],
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "defaultMccBlocksLifted": false,
      "currency": "USD",
      "processorRef": "card_b81c2a4f",
      "issuerRef": "lead_card_7a1b9c3d"
    },
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "agentCardKind": "STANDARD",
    "effectiveBlockedMccs": [
      "7995",
      "6051"
    ],
    "spendLimit": {
      "amount": 2300,
      "duration": "TRANSACTION"
    },
    "reservedAmount": 2300,
    "expiresAt": "2026-10-10T15:30:00Z"
  },
  "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"
}

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

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

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

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

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

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.

Maximum string length: 255

Example:

"<uuid>"

Path Parameters

quoteId

string

required

The unique identifier of the quote to execute

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 — in that case the action will transition to FAILED.

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.

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`	Not executed, or execution failed; see `failureReason`

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 quote
`ISSUE_PURCHASE_CARD`	Issue a purchase card

Available options:

EXECUTE_QUOTE,

ISSUE_PURCHASE_CARD

expiresAt

string<date-time>

required

When the action expires. For EXECUTE_QUOTE, this is the quote's own expiry. A PENDING_APPROVAL action that reaches this time transitions to FAILED with failureReason QUOTE_EXPIRED; approval never creates a replacement quote. An ISSUE_PURCHASE_CARD action expires five minutes after it is submitted and then fails with APPROVAL_EXPIRED.

Example:

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

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

Agent Quote · object

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

Show child attributes

purchaseCard

Single-Use Card · object

The purchase card requested. Present for ISSUE_PURCHASE_CARD, so an approval decision can show its kind, amount or cap, and source account.

Single-Use Card
Merchant-Locked Card

Show child attributes

card

Agent Card · object

The issued purchase card, populated once an ISSUE_PURCHASE_CARD action has completed.

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

failureReason

enum<string>

Machine-readable reason the action failed. Only present when status is FAILED; rejectionReason is used only for REJECTED actions.

Available options:

QUOTE_EXPIRED,

POLICY_DENIED,

AGENT_INACTIVE,

EXECUTION_FAILED,

CARD_ISSUANCE_FAILED,

APPROVAL_EXPIRED,

PRICE_MOVED

Using the API

API documentation

Execute a quote

Authorizations

Headers

Path Parameters

Response