> ## Documentation Index > Fetch the complete documentation index at: https://ramps-kph-agent-spec-amendments.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List agent cards > List the cards that belong to the authenticated agent: standard cards the customer issued for it and purchase cards it issued. Other cards of the customer are not listed. Requires the MANAGE_CARDS permission. ## OpenAPI ````yaml /openapi.yaml get /agents/me/cards openapi: 3.1.0 info: title: Grid 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: Platform Configuration description: >- Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard. - name: Customers description: >- Customer management endpoints for creating and updating customer information - name: Contact Verification description: >- Endpoints for verifying a customer's email and phone via one-time codes. Required only for customers whose payment provider mandates contact verification (e.g. EU customers); other providers return 409. - name: Strong Customer Authentication description: >- Endpoints for authorizing money-movement operations that require Strong Customer Authentication. Relevant only for customers in a region where SCA is required (e.g. EU); customers outside SCA-regulated regions never see an SCA challenge and these endpoints return 409. - name: KYC/KYB Verifications description: >- Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers. - name: Documents description: >- Endpoints for uploading and managing verification documents for customers and beneficial owners. Supports KYC and KYB document requirements. - name: Internal Accounts description: >- Internal account management endpoints for creating and managing internal accounts - name: Periodic Statements description: > Build, deliver, and evidence a Regulation E periodic statement for a customer's internal account. A statement period is a calendar month in US Central time (`America/Chicago`). A statement is issued for each customer's own USD internal account and covers their whole balance. Money received through a rule-based account appears on its owner's statement; rule-based, bulk settlement and platform-owned accounts have no statement of their own. **1. The statement — `GET /internal-accounts/{id}/balance-changes?startDate=&endDate=`** One row per change to the balance, in the order the money moved, with the opening and closing balances for the window in the same response. Page until `hasMore` is false, then assert this identity across every page before you render anything: ``` openingBalance + Σ(data[].amount) == closingBalance ``` If it does not hold, do not send the statement; contact support instead. `startDate` and `endDate` bound a half-open window `[startDate, endDate)`: for a monthly statement, pass the first instant of the month and the first instant of the following month, both in US Central time (for August 2026, `2026-08-01T00:00:00-05:00` and `2026-09-01T00:00:00-05:00`). Grid records a statement as fetched only for a window that is exactly one such month. **2. The receipt — `POST /internal-accounts/{id}/confirm-statement`** Once a month, after you have pulled and issued a period's statement, send a receipt with the `statementMonth` it covers. Grid stores it as the delivery record for that account and period. Sending it again is harmless: the first receipt's time is kept. **Timing** A window whose card settlement has not closed is refused with `409 NOT_YET_AVAILABLE` rather than answered with figures that could still change; retry once it has settled. - name: External Accounts description: >- External account management endpoints for creating and managing external bank accounts - name: Same-Currency Transfers description: >- Deprecated endpoints for transferring funds between internal and external accounts with the same currency. Use the quote endpoints under Cross-Currency Transfers instead, which now serve same-currency transfers as well. - name: Cross-Currency Transfers description: >- Endpoints for creating and confirming quotes for transfers, both same-currency and cross-currency - name: Transactions description: Endpoints for retrieving transaction information - name: Webhooks description: Webhook endpoints and configuration for receiving notifications - name: Invitations description: Endpoints for creating, claiming and managing UMA invitations - name: Sandbox description: Endpoints to trigger test cases in sandbox - name: API Tokens description: Endpoints to programmatically manage API tokens - name: Exchange Rates description: >- Endpoints for retrieving cached foreign exchange rates. Rates are cached for approximately 5 minutes and include platform-specific fees. - name: Discoveries description: >- Endpoints for discovering available payment rails, banks, and providers for a given country and currency corridor. - name: Embedded Wallet Auth description: >- Endpoints for registering and verifying end-user authentication credentials (email OTP, OAuth, passkey) used to sign Embedded Wallet actions. - name: Agent Management description: >- Endpoints for creating and managing agents (experimental), called by the partner's backend using platform credentials. Covers the full agent lifecycle: creation, policy configuration, pausing, deletion, the device code installation flow, and approving or rejecting transactions initiated by agents. - name: Agent Operations description: >- Experimental 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`. - name: Cards description: >- Card management endpoints. Issue debit cards against an internal account, freeze / unfreeze, close, manage a card's funding source, and list card transactions. - name: Stablecoins description: >- Stablecoin issuance endpoints. Link provider accounts, register provider-created stablecoins, create direct mint/burn issuer operations, and track operation status. paths: /agents/me/cards: get: tags: - Agent Operations summary: List agent cards description: >- List the cards that belong to the authenticated agent: standard cards the customer issued for it and purchase cards it issued. Other cards of the customer are not listed. Requires the MANAGE_CARDS permission. operationId: agentListCards parameters: - name: kind in: query description: Filter by card kind required: false schema: $ref: '#/components/schemas/AgentCardKind' - name: status in: query description: Filter by card status required: false schema: $ref: '#/components/schemas/CardStatus' - 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/AgentCardListResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: >- Forbidden - Agents API or agent cards are not enabled for the platform, the agent does not have the MANAGE_CARDS permission, or the customer is not verified content: application/json: schema: $ref: '#/components/schemas/Error403' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' security: - AgentAuth: [] components: schemas: AgentCardKind: type: string enum: - STANDARD - SINGLE_USE - MERCHANT_LOCKED description: > How an agent card is used and funded. | Kind | Description | |------|-------------| | `STANDARD` | A card the customer issued for the agent on the platform. The customer holds the card details and its spend is the customer's own; the agent can read it, tighten its limits, and freeze it. | | `SINGLE_USE` | A purchase card the agent issued for one purchase. Its spend is reserved against the agent's policy at issuance and the card closes after its first authorization. | | `MERCHANT_LOCKED` | A purchase card the agent issued for repeated purchases at one merchant, such as a subscription, capped by a monthly limit. Each authorization is checked against the agent's policy. | CardStatus: type: string enum: - PENDING_KYC - PROCESSING - PENDING_AUTH - ACTIVE - FROZEN - CLOSED description: > Lifecycle status of a card. | Status | Description | |-------|-------------| | `PENDING_KYC` | The cardholder has not yet completed KYC. Cards in this status cannot transact. | | `PROCESSING` | The card has been requested and is being provisioned with the issuer. | | `PENDING_AUTH` | The issuer has provisioned the card, but its USDB Embedded Wallet funding source lacks an active delegated signing key. Complete `POST /auth/delegated-keys` before using the card. | | `ACTIVE` | The card is live and can authorize transactions. | | `FROZEN` | The card is temporarily disabled by the platform. New authorizations are declined with `cardDeclinedReason: CARD_NOT_ACTIVE`. Existing settlements and refunds continue to reconcile. | | `CLOSED` | The card is permanently closed. Terminal, irreversible status. | AgentCardListResponse: type: object required: - data - hasMore properties: data: type: array description: Cards that belong to the authenticated agent. items: $ref: '#/components/schemas/AgentCard' hasMore: type: boolean description: Indicates if more results are available beyond this page. nextCursor: type: string description: >- Cursor to retrieve the next page of results (only present if hasMore is true). example: Card:019542f5-b3e7-1d02-0000-000000000010 totalCount: type: integer description: Total number of cards matching the criteria (excluding pagination). example: 3 Error401: type: object required: - reason - code properties: code: type: string description: > | Error Code | Description | |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | | REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) | enum: - UNAUTHORIZED - INVALID_SIGNATURE - WALLET_SIGNATURE_MISSING - WALLET_SIGNATURE_MALFORMED - WALLET_SIGNATURE_BODY_MISMATCH - WALLET_SIGNATURE_INVALID - REQUEST_ID_MISSING reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error403: type: object required: - reason - code properties: code: type: string description: > | Error Code | Description | |------------|-------------| | FORBIDDEN | Insufficient permissions | | USER_NOT_READY | Customer exists but is not ready for operation | | COUNTERPARTY_NOT_ALLOWED | Counterparty has not been enabled for your account | | VELOCITY_LIMIT_EXCEEDED | Counterparty has exceeded velocity limits | | END_USER_TERMS_NOT_ACCEPTED | Customer has not accepted the End User Terms | | CUSTOMER_NOT_VERIFIED | The customer is not verified and cannot perform this action | | SANCTION_BLOCKED | Blocked by sanction screening | enum: - FORBIDDEN - USER_NOT_READY - COUNTERPARTY_NOT_ALLOWED - VELOCITY_LIMIT_EXCEEDED - END_USER_TERMS_NOT_ACCEPTED - CUSTOMER_NOT_VERIFIED - SANCTION_BLOCKED reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error500: type: object required: - reason - code properties: code: type: string description: | | Error Code | Description | |------------|-------------| | GRID_SWITCH_ERROR | Grid switch error | | INTERNAL_ERROR | Internal server or UMA error | enum: - GRID_SWITCH_ERROR - INTERNAL_ERROR reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true AgentCard: title: Agent Card type: object description: >- A card that belongs to the authenticated agent: the card itself and how the agent may use it. required: - card - agentId - agentCardKind - effectiveBlockedMccs properties: card: $ref: '#/components/schemas/Card' agentId: type: string description: The agent the card belongs to. example: Agent:019542f5-b3e7-1d02-0000-000000000042 agentCardKind: $ref: '#/components/schemas/AgentCardKind' spendLimit: $ref: '#/components/schemas/AgentCardSpendLimit' description: The issuer-enforced cap. Present for purchase cards. reservedAmount: type: integer format: int64 minimum: 0 description: >- Amount of the agent's spending limits currently held for this card, in the smallest unit of the card's currency. Present for purchase cards. example: 2300 effectiveBlockedMccs: type: array description: >- Every merchant category code the card declines: `blockedMccs` plus the categories Grid blocks for agent cards, unless the platform lifted those defaults on a `STANDARD` card (`defaultMccBlocksLifted`). A purchase card's defaults cannot be lifted. items: type: string pattern: ^[0-9]{4}$ example: - '7995' - '6051' expiresAt: type: string format: date-time description: >- When Grid closes the card if it is still open. An unused `SINGLE_USE` card closes at this time and releases its reservation. example: '2026-10-10T15:30:00Z' Card: type: object required: - id - customerId - status - form - fundingSource - maxSpendPerTransaction - maxSpendPerDay - maxTransactionsPerDay - createdAt - updatedAt properties: id: type: string description: System-generated unique card identifier example: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: type: string description: The id of the `Customer` who holds this card. example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCardId: type: string description: Platform-specific card identifier generated by the server. example: card-emp-001 status: $ref: '#/components/schemas/CardStatus' statusReason: $ref: '#/components/schemas/CardStatusReason' description: >- Reason associated with the current `status`. Present when the card is `PENDING_AUTH`, `CLOSED`, or when provisioning was rejected; absent otherwise. brand: $ref: '#/components/schemas/CardBrand' form: $ref: '#/components/schemas/CardForm' pinStatus: $ref: '#/components/schemas/CardPinStatus' pinUnblockAvailableAt: type: string format: date-time readOnly: true description: >- Earliest time another PIN unblock attempt is allowed. Absent until the unblock allowance is used. Changing the PIN does not reset this time. example: '2026-10-15T15:00:00Z' last4: type: string description: Last four digits of the card PAN. example: '4242' expMonth: type: integer minimum: 1 maximum: 12 description: Card expiration month (1–12). example: 12 expYear: type: integer description: Card expiration year (four digits). example: 2029 fundingSource: type: string description: Internal account id that funds this card. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 cardCapabilities: $ref: '#/components/schemas/CardCapabilities' description: >- Actions supported for this card by the issuer selected at issuance. Present for cards whose program has been resolved; absent otherwise. These capabilities are fixed at issuance for the card's lifetime. maxSpendPerTransaction: anyOf: - type: integer format: int64 minimum: 1 maximum: 9007199254740991 - type: 'null' description: >- The largest amount this card can authorize on a single transaction, in the smallest unit of its `currency` (cents for USD). An authorization for exactly the limit is allowed. A later clearing can still settle above it — a restaurant tip, for example — so this caps the authorization, not the final settled amount. `null` means the card sets no limit of its own. If your platform config also sets `cardConfigs.maxSpendPerTransaction` (the platform-level limit), the lower of the two applies and this value stays as you set it. example: 5000 maxSpendPerDay: anyOf: - type: integer format: int64 minimum: 1 maximum: 9007199254740991 - type: 'null' description: >- Card-specific cap on cumulative new spend during one UTC calendar day, in the smallest unit of the card's `currency`. The window resets at 00:00 UTC. Null means the card has no card-specific daily cap. When the platform config also supplies `cardConfigs.maxSpendPerDay`, Grid enforces the lower of the two values without replacing this configured value. Refunds, reversals, and authorization expiries do not restore capacity during the day. Spend exactly equal to the effective limit is allowed. example: 25000 maxTransactionsPerDay: anyOf: - type: integer format: int32 minimum: 1 maximum: 2147483647 - type: 'null' description: >- Card-specific cap on the number of transactions the card may authorize during one UTC calendar day. The window resets at 00:00 UTC. Null means the card has no card-specific daily transaction cap. When the platform config also supplies `cardConfigs.maxTransactionsPerDay`, Grid enforces the lower of the two values without replacing this configured value. Each approved authorization counts once for the day it was authorized; refunds, reversals, and authorization expiries do not restore capacity during the day. A transaction that brings the day's count exactly to the effective limit is allowed. example: 20 allowedMccs: type: array minItems: 1 description: >- Merchant category codes the card may spend at. Absent when the card may spend at any category not blocked. items: type: string pattern: ^[0-9]{4}$ example: - '5411' blockedMccs: type: array description: >- Merchant category codes the card declines, with `cardDeclinedReason: BLOCKED`. A card issued for an agent also declines Grid's default agent categories unless `defaultMccBlocksLifted` is true; see `AgentCard.effectiveBlockedMccs`. items: type: string pattern: ^[0-9]{4}$ example: - '7995' agentId: type: string description: The agent the card was issued for, when there is one. example: Agent:019542f5-b3e7-1d02-0000-000000000042 defaultMccBlocksLifted: type: boolean description: >- Whether the platform lifted Grid's default agent merchant-category blocks on this card. Present only for a card issued for an agent; always false for a purchase card. example: false currency: type: string description: >- Currency the card transacts in, fixed at issuance by its card program. USDB-funded cards transact in USD, with funding converted at 1 USDB = 1 USD. Spending limits use the smallest unit of the card's currency (USD cents for USDB-funded cards). Changing the funding source does not change the card's currency or spending-limit units. example: USD processorRef: type: string description: >- Opaque processor-side reference for the card (e.g. the Lithic card token). Useful for cross-referencing in the processor's dashboards; not used for any Grid request routing. example: card_b81c2a4f issuerRef: type: string description: >- Opaque identifier for the card on the issuer of record (e.g. the Lead Bank account/card identifier). Useful for cross-referencing in issuer dashboards; not used for any Grid request routing. example: lead_card_7a1b9c3d createdAt: type: string format: date-time description: Creation timestamp example: '2026-05-08T14:10:00Z' updatedAt: type: string format: date-time description: Last update timestamp example: '2026-05-08T14:11:00Z' AgentCardSpendLimit: type: object description: >- The spend cap the card issuer enforces for a purchase card, in the smallest unit of the card's currency. required: - amount - duration properties: amount: type: integer format: int64 minimum: 1 description: >- The cap. For a `SINGLE_USE` card this is the requested amount plus the tolerance Grid allows for tips and final amounts. example: 2300 duration: type: string enum: - TRANSACTION - MONTHLY description: >- `TRANSACTION` caps the card's single purchase; `MONTHLY` caps spend per calendar month. example: TRANSACTION CardStatusReason: type: string enum: - DELEGATION_REQUIRED - ISSUER_REJECTED - CLOSED_BY_PLATFORM - CLOSED_BY_GRID description: > Reason a card reached a terminal or non-active status. Present on `PENDING_AUTH` and `CLOSED` cards, and on cards that fail provisioning before reaching `ACTIVE`. | Reason | Description | |--------|-------------| | `DELEGATION_REQUIRED` | The card funding source has no usable delegated signing key. Present while the card is `PENDING_AUTH`. | | `ISSUER_REJECTED` | The card issuer rejected provisioning during `PROCESSING`. | | `CLOSED_BY_PLATFORM` | The card was closed via `PATCH /cards/{id}` (`status: CLOSED`) by the platform. | | `CLOSED_BY_GRID` | The card was closed by Grid (e.g. compliance or risk action). | CardBrand: type: string enum: - VISA - MASTERCARD description: | Card network brand. Read-only — determined by Grid when the card is provisioned with the issuer. CardForm: type: string enum: - VIRTUAL description: | Physical form factor of the card. Only `VIRTUAL` is supported in v1; `PHYSICAL` will be added in a later release. CardPinStatus: type: string enum: - NOT_SET - OK - BLOCKED example: OK description: > State of the card's PIN. On the Card resource, this is the last known status and is present whenever PIN management is supported. An absent value means PIN management is unavailable for this card; it does not mean `NOT_SET`. Use `GET /cards/{id}` to retrieve `pinStatus`. | Status | Description | |--------|-------------| | `NOT_SET` | No PIN has been set on the card. PIN verification is not enabled. Set one with `POST /cards/{id}/set-pin` or the hosted form returned by `GET /cards/{id}/pin-entry-url`. | | `OK` | A PIN is set and usable. | | `BLOCKED` | The PIN was entered incorrectly three consecutive times and is refused until cleared with `POST /cards/{id}/pin/unblock`, or replaced with `POST /cards/{id}/set-pin`. | CardCapabilities: type: object description: Actions supported by the card program associated with this resource. required: - supportsSpendLimits - supportsSpendLimitsAtIssuance - supportsTransactionCountLimit - supports3dSecurePassword - supportsPanReveal - supportsDigitalWalletTokenization properties: supportsSpendLimits: type: boolean description: >- Whether a card in this program can have `maxSpendPerTransaction` and `maxSpendPerDay` at all. On card programs where the card issuer makes authorization decisions, these limits can only be set after issuance through `PATCH /cards/{id}`. Check `supportsSpendLimitsAtIssuance` to determine whether you can supply them when issuing a card. example: true supportsSpendLimitsAtIssuance: type: boolean description: >- Whether `maxSpendPerTransaction` and `maxSpendPerDay` may be supplied on `POST /cards`. This is true for card programs where Grid makes the authorization decision and false for card programs where the card issuer makes authorization decisions. example: true supportsTransactionCountLimit: type: boolean description: Whether cards in this program accept `maxTransactionsPerDay`. example: true supports3dSecurePassword: type: boolean description: >- Whether cards in this program accept a caller-supplied `threeDSecurePassword`. example: false supportsPanReveal: type: boolean description: >- Whether cards in this program can be revealed through `POST /cards/{id}/reveal`. example: true supportsDigitalWalletTokenization: type: boolean description: >- Whether cards in this program can be added to Apple Pay, Google Pay, or Samsung Pay from your app through `POST /cards/{id}/tokenize`. Manual entry into a wallet works regardless of this flag. example: true securitySchemes: BasicAuth: type: http scheme: basic description: >- API token authentication using format `:` AgentAuth: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.