Lightspark Agent Operations API

openapi: 3.1.0
info:
  title: Grid Agent Management Agent Operations API
  description: 'API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/.

    '
  version: '2025-10-13'
  contact:
    name: Lightspark Support
    email: support@lightspark.com
  license:
    name: Proprietary
    url: https://lightspark.com/terms
servers:
- url: https://api.lightspark.com/grid/2025-10-13
  description: Production server
security:
- BasicAuth: []
- AgentAuth: []
tags:
- name: Agent Operations
  description: Endpoints called by the agent itself using its own credentials (obtained via device code redemption). Scoped to the agent's associated customer — all requests automatically operate on behalf of that customer and are subject to the agent's policy. When an action requires approval, the resulting transaction enters a pending state and must be approved by the platform via `POST /transactions/{transactionId}/approve`.
paths:
  /agents/me:
    get:
      summary: Get current agent
      description: 'Retrieve the authenticated agent''s own profile, policy, and current usage. This endpoint is called by the agent software itself using its own credentials (obtained via device code redemption) rather than platform credentials.

        '
      operationId: getAgentMe
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/transactions:
    get:
      summary: List agent transactions
      description: 'Retrieve a paginated list of transactions for the authenticated agent''s customer. Results are automatically scoped to the agent''s associated customer — no customer filter is needed or accepted.

        '
      operationId: agentListTransactions
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      parameters:
      - name: accountIdentifier
        in: query
        description: Filter by account identifier (matches either sender or receiver)
        required: false
        schema:
          type: string
      - name: senderAccountIdentifier
        in: query
        description: Filter by sender account identifier
        required: false
        schema:
          type: string
      - name: receiverAccountIdentifier
        in: query
        description: Filter by receiver account identifier
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: Filter by transaction status
        required: false
        schema:
          $ref: '#/components/schemas/TransactionStatus'
      - name: type
        in: query
        description: Filter by transaction type
        required: false
        schema:
          $ref: '#/components/schemas/TransactionType'
      - name: reference
        in: query
        description: Filter by reference
        required: false
        schema:
          type: string
      - name: startDate
        in: query
        description: Filter by start date (inclusive) in ISO 8601 format
        required: false
        schema:
          type: string
          format: date-time
      - name: endDate
        in: query
        description: Filter by end date (inclusive) in ISO 8601 format
        required: false
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: Maximum number of results to return (default 20, max 100)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        description: Cursor for pagination (returned from previous request)
        required: false
        schema:
          type: string
      - name: sortOrder
        in: query
        description: Order to sort results in
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/transactions/{transactionId}:
    parameters:
    - name: transactionId
      in: path
      description: Unique identifier of the transaction
      required: true
      schema:
        type: string
    get:
      summary: Get agent transaction by ID
      description: 'Retrieve a specific transaction belonging to the authenticated agent''s customer. Returns 404 if the transaction exists but belongs to a different customer.

        '
      operationId: agentGetTransaction
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionOneOf'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/quotes:
    post:
      summary: Create a transfer quote
      description: 'Generate a quote for a cross-currency transfer on behalf of the authenticated agent''s customer. Accounts referenced in the request must belong to the agent''s customer. Requires the CREATE_QUOTES permission in the agent''s policy.

        If the agent''s defaultExecutionMode is APPROVAL_REQUIRED, or the quote amount exceeds the agent''s approvalThresholds, the resulting transaction will require explicit approval before funds move.

        '
      operationId: agentCreateQuote
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: '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.

          '
        schema:
          type: string
          example: <uuid>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
      responses:
        '201':
          description: Transfer quote created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          description: Bad request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden - Agent policy does not permit this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '412':
          description: Counterparty doesn't support UMA version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error412'
        '424':
          description: Counterparty issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error424'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/quotes/{quoteId}:
    parameters:
    - name: quoteId
      in: path
      description: ID of the quote to retrieve
      required: true
      schema:
        type: string
    get:
      summary: Get agent quote by ID
      description: 'Retrieve a quote created by the authenticated agent. Returns 404 if the quote exists but was not created by this agent.

        '
      operationId: agentGetQuote
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      responses:
        '200':
          description: Quote retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Quote not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/quotes/{quoteId}/execute:
    parameters:
    - name: quoteId
      in: path
      required: true
      description: The unique identifier of the quote to execute
      schema:
        type: string
      example: Quote:019542f5-b3e7-1d02-0000-000000000001
    post:
      summary: Execute a quote
      description: 'Execute a quote created by the authenticated agent. Requires the EXECUTE_QUOTES permission in the agent''s policy.

        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`.

        Once executed, the quote cannot be cancelled.

        '
      operationId: agentExecuteQuote
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: '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.

          '
        schema:
          type: string
          example: <uuid>
      - name: Grid-Wallet-Signature
        in: header
        required: false
        description: Full Grid wallet signature over the `payloadToSign` returned in the quote's `paymentInstructions[].accountOrWalletInfo` entry, produced with the session private key of a verified authentication credential on the source Embedded Wallet. Required when the quote's source is an internal account of type `EMBEDDED_WALLET`; ignored for other source types.
        schema:
          type: string
        example: eyJwdWJsaWNLZXkiOiIwMmExYjIuLi4iLCJzY2hlbWUiOiJTSUdOQVRVUkVfU0NIRU1FX1RLX0FQSV9QMjU2Iiwic2lnbmF0dXJlIjoiMzA0NTAyMjEwMC4uLiJ9
      responses:
        '200':
          description: '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`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAction'
        '400':
          description: Bad request - Quote cannot be executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized. Also returned when the quote's source is an internal account of type `EMBEDDED_WALLET` and the provided `Grid-Wallet-Signature` header is missing, malformed, or does not match the quote's `payloadToSign`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden - Agent policy does not permit this operation or spending limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Quote not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '409':
          description: Conflict - Quote already executed, expired, or in invalid state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/actions:
    get:
      summary: List agent's own actions
      description: 'Retrieve a paginated list of actions submitted by the authenticated agent. Use this to poll for approval decisions after submitting an action that requires approval.

        '
      operationId: agentListActions
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      parameters:
      - name: status
        in: query
        description: Filter by action status
        required: false
        schema:
          $ref: '#/components/schemas/AgentActionStatus'
      - name: limit
        in: query
        description: Maximum number of results to return (default 20, max 100)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        description: Cursor for pagination (returned from previous request)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentActionListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/actions/{actionId}:
    parameters:
    - name: actionId
      in: path
      description: Unique identifier of the agent action
      required: true
      schema:
        type: string
    get:
      summary: Get an agent action
      description: 'Retrieve a specific action submitted by the authenticated agent. Poll this endpoint after submitting an action that requires approval to check whether it has been approved, rejected, or has failed.

        '
      operationId: agentGetAction
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAction'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/transfer-in:
    post:
      summary: Create a transfer-in
      description: 'Transfer funds from an external account to an internal account for the authenticated agent''s customer. Accounts must belong to the agent''s customer. Requires the CREATE_TRANSFERS permission in the agent''s policy.

        If the agent''s policy requires approval for this amount, the transaction will be created in a pending state and must be approved by the platform via `POST /agents/{agentId}/actions/{actionId}/approve`.

        This endpoint should only be used for external account sources with pull functionality (e.g. ACH Pull). Otherwise, use the payment instructions on the internal account to deposit funds.

        '
      operationId: agentCreateTransferIn
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: '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.

          '
        schema:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferInRequest'
            examples:
              transferIn:
                summary: Transfer from external to internal account
                value:
                  source:
                    accountId: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  destination:
                    accountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                  amount: 12550
      responses:
        '201':
          description: 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAction'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden - Agent policy does not permit this operation or spending limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/transfer-out:
    post:
      summary: Create a transfer-out
      description: 'Transfer funds from an internal account to an external account for the authenticated agent''s customer. Accounts must belong to the agent''s customer. Requires the CREATE_TRANSFERS permission in the agent''s policy.

        If the agent''s policy requires approval for this amount, the transaction will be created in a pending state and must be approved by the platform via `POST /agents/{agentId}/actions/{actionId}/approve`.

        '
      operationId: agentCreateTransferOut
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: '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.

          '
        schema:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferOutRequest'
            examples:
              transferOut:
                summary: Transfer from internal to external account
                value:
                  source:
                    accountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                  destination:
                    accountId: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  amount: 12550
      responses:
        '201':
          description: 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAction'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden - Agent policy does not permit this operation or spending limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/internal-accounts:
    get:
      summary: List agent's internal accounts
      description: 'Retrieve the internal accounts belonging to the customer this agent operates on behalf of. Use this to discover available source accounts for transfers and quotes, and to verify which accounts are accessible under the agent''s `accountRestrictions` policy.

        '
      operationId: agentListInternalAccounts
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      parameters:
      - name: currency
        in: query
        description: Filter by currency code
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: Filter by internal account type. Use `EMBEDDED_WALLET` to find the self-custodial wallet provisioned for the customer, or `INTERNAL_FIAT` / `INTERNAL_CRYPTO` for platform-managed holding accounts.
        required: false
        schema:
          $ref: '#/components/schemas/InternalAccountType'
      - name: limit
        in: query
        description: Maximum number of results to return (default 20, max 100)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        description: Cursor for pagination (returned from previous request)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalAccountListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/external-accounts:
    get:
      summary: List agent external accounts
      description: 'Retrieve a paginated list of external accounts belonging to the authenticated agent''s customer. Requires the MANAGE_EXTERNAL_ACCOUNTS permission in the agent''s policy.

        '
      operationId: agentListExternalAccounts
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      parameters:
      - name: currency
        in: query
        description: Filter by currency code
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of results to return (default 20, max 100)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        description: Cursor for pagination (returned from previous request)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccountListResponse'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    post:
      summary: Add an external account
      description: 'Register a new external bank account or wallet for the authenticated agent''s customer. Requires the MANAGE_EXTERNAL_ACCOUNTS permission in the agent''s policy. The `customerId` field is optional and will be inferred from the agent''s associated customer if omitted.

        '
      operationId: agentCreateExternalAccount
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalAccountCreateRequest'
            examples:
              usBankAccount:
                summary: Create external US bank account
                value:
                  currency: USD
                  accountInfo:
                    accountType: USD_ACCOUNT
                    accountNumber: '12345678901'
                    routingNumber: '123456789'
                    bankAccountType: CHECKING
                    bankName: Chase Bank
                    beneficiary:
                      beneficiaryType: INDIVIDUAL
                      fullName: John Doe
                      birthDate: '1990-01-15'
                      nationality: US
                      address:
                        line1: 123 Main Street
                        city: San Francisco
                        state: CA
                        postalCode: '94105'
                        country: US
              sparkWallet:
                summary: Create external Spark wallet
                value:
                  currency: BTC
                  accountInfo:
                    accountType: SPARK_WALLET
                    address: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu
      responses:
        '201':
          description: External account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccount'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - External account already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /agents/me/external-accounts/{externalAccountId}:
    parameters:
    - name: externalAccountId
      in: path
      description: System-generated unique external account identifier
      required: true
      schema:
        type: string
    get:
      summary: Get agent external account by ID
      description: 'Retrieve an external account belonging to the authenticated agent''s customer. Returns 404 if the account exists but belongs to a different customer. Requires the MANAGE_EXTERNAL_ACCOUNTS permission in the agent''s policy.

        '
      operationId: agentGetExternalAccount
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccount'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: External account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    delete:
      summary: Delete agent external account
      description: 'Delete an external account belonging to the authenticated agent''s customer. Requires the MANAGE_EXTERNAL_ACCOUNTS permission in the agent''s policy.

        '
      operationId: agentDeleteExternalAccount
      tags:
      - Agent Operations
      security:
      - AgentAuth: []
      responses:
        '204':
          description: External account deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: External account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
components:
  schemas:
    EurAccountInfoBase:
      type: object
      required:
      - accountType
      - iban
      properties:
        accountType:
          type: string
          enum:
          - EUR_ACCOUNT
        iban:
          type: string
          description: The IBAN of the bank account
          example: DE893704004405

# --- truncated at 32 KB (313 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightspark/refs/heads/main/openapi/lightspark-agent-operations-api-openapi.yml