> ## Documentation Index > Fetch the complete documentation index at: https://docs.natural.com/llms.txt > Use this file to discover all available pages before exploring further. # List transactions > List transactions visible to your party. ## OpenAPI ````yaml /api-reference/openapi.json get /transactions openapi: 3.1.1 info: title: Natural API version: 0.2.0 description: >- Natural's payments API for autonomous agents. **Base URL:** `https://api.natural.co` Agents and coding assistants should prefer the hosted MCP server at `https://mcp.natural.co` when an MCP-aware host runs the agent, the Natural CLI for terminal/CI workflows, and the official SDKs for application runtimes they own. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required. For support: support@natural.co servers: - url: https://api.natural.co description: Production security: [] tags: - name: Agents description: Agent management - name: Customers description: Customer management - name: Counterparties description: Counterparty management - name: Payments description: Payment operations - name: Transactions description: Transaction activity and history operations - name: Transfers description: Deposit and withdrawal operations - name: PaymentRequests description: Payment-request management - name: Approvals description: Approval review operations - name: Invitations description: Party invitation management - name: Identity description: Caller identity introspection - name: Parties description: Party and organization management - name: Wallets description: Wallet balance, deposits, withdrawals, and external accounts - name: External Accounts description: Linked external bank accounts - name: API Keys description: API key management - name: Agent Keys description: Agent key management - name: Webhooks description: Webhook endpoint management - name: Events description: Webhook event log access paths: /transactions: get: tags: - Transactions summary: List transactions description: List transactions visible to your party. operationId: transactions.list parameters: - name: type in: query schema: enum: - payment - transfer - all type: string default: all allowEmptyValue: true allowReserved: true - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Results per page allowEmptyValue: true allowReserved: true - name: cursor in: query schema: type: string description: Pagination cursor from previous response allowEmptyValue: true allowReserved: true - name: counterpartyPartyId in: query schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: >- Restrict results to transactions whose payment counterparty is this party. allowEmptyValue: true allowReserved: true - name: walletId in: query schema: type: string pattern: ^wal_[0-9a-f]{32}$ description: Restrict results to transactions visible through this wallet. allowEmptyValue: true allowReserved: true - name: customerPartyId in: query schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: >- Restrict results to delegated customer activity executed on behalf of this customer party. This maps to the transaction subject party, not the payment counterparty. allowEmptyValue: true allowReserved: true - name: delegated in: query schema: type: boolean description: >- When true, restrict results to transactions executed through an agent delegation (agentDelegationId IS NOT NULL) — the connection-scoped feed. allowEmptyValue: true allowReserved: true - name: X-Agent-ID in: header required: false schema: anyOf: - type: string - type: 'null' description: Agent ID (agt_xxx) identifying which agent is making the request. - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: >- Required when X-Agent-ID is present. Session or conversation ID for agent observability. responses: '200': description: Successful Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: type: type: string enum: - transaction id: type: string pattern: ^txn_[0-9a-f]{32}$ description: Transaction handle (txn_xxx) attributes: type: object properties: amount: type: integer description: Amount in cents currency: type: string description: Currency code status: type: string description: Transaction status createdAt: type: string description: When this transaction was created transactionType: enum: - payment - transfer type: string description: 'Transaction type: payment | transfer' direction: enum: - INBOUND - OUTBOUND type: string description: 'Direction: INBOUND | OUTBOUND' description: anyOf: - type: string - type: 'null' description: Payment description updatedAt: anyOf: - type: string - type: 'null' description: When this transaction was last updated expectedAvailableAt: anyOf: - type: string - type: 'null' description: >- Projected funds-available time for transfers. Null when no projection exists and null for payments. required: - amount - currency - status - createdAt - transactionType - direction - description - updatedAt - expectedAvailableAt additionalProperties: false title: TransactionAttributes description: Resource attributes relationships: type: object properties: sourceParty: type: object properties: data: anyOf: - type: object properties: type: description: Resource type type: string enum: - party id: type: string pattern: ^pty_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Source party destinationParty: type: object properties: data: anyOf: - type: object properties: type: description: Resource type type: string enum: - party id: type: string pattern: ^pty_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: Destination party payment: type: object properties: data: type: object properties: type: description: Resource type type: string enum: - payment id: type: string pattern: ^pay_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier required: - data additionalProperties: false description: >- Payment that produced this transaction. Present only when the authenticated caller can access the payment resource. transfer: type: object properties: data: type: object properties: type: description: Resource type type: string enum: - transfer id: type: string pattern: ^trf_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier required: - data additionalProperties: false description: >- Transfer that produced this transaction. Present only when the authenticated caller can access the transfer resource. wallet: type: object properties: data: type: object properties: type: description: Resource type type: string enum: - wallet id: type: string pattern: ^wal_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier required: - data additionalProperties: false description: >- Wallet whose ledger row made this transaction visible. required: - sourceParty - destinationParty additionalProperties: false title: TransactionRelationships description: Resource relationships required: - type - id - attributes - relationships additionalProperties: false title: TransactionResource meta: type: object properties: pagination: type: object properties: hasMore: type: boolean nextCursor: anyOf: - type: string - type: 'null' required: - hasMore - nextCursor additionalProperties: false title: PaginationMeta required: - pagination additionalProperties: false required: - data - meta additionalProperties: false title: TransactionListResponse examples: default: summary: Default value: data: - type: transaction id: txn_650e8400e29b41d4a716446655440000 attributes: amount: 50000 currency: USD status: PROCESSING description: Cash in createdAt: '2026-01-04T15:30:00Z' updatedAt: '2026-01-04T15:31:00Z' transactionType: transfer direction: INBOUND expectedAvailableAt: null relationships: sourceParty: data: null destinationParty: data: type: party id: pty_7c9e6679e29b41d4a716446655440001 transfer: data: type: transfer id: trf_650e8400e29b41d4a716446655440000 meta: pagination: hasMore: false nextCursor: null headers: X-RateLimit-Limit: description: Maximum requests allowed per window schema: type: integer X-RateLimit-Remaining: description: Requests remaining in current window schema: type: integer X-RateLimit-Reset: description: Unix timestamp when rate limit resets schema: type: integer '400': description: Validation Error content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: invalid_value detail: A request value is invalid. status: '400' meta: supportId: req_a1b2c3d4e5f6 '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: unauthenticated detail: Authentication is required. status: '401' meta: supportId: req_a1b2c3d4e5f6 '403': description: Forbidden content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: >- Not Found — returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': description: Validation Error content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: invalid_value detail: 'email: Invalid email address' status: '422' source: pointer: /data/attributes/email meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying schema: type: integer X-RateLimit-Limit: description: Maximum requests allowed per window schema: type: integer X-RateLimit-Remaining: description: Requests remaining in current window schema: type: integer X-RateLimit-Reset: description: Unix timestamp when rate limit resets schema: type: integer '500': description: Internal Server Error content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: bad_gateway detail: >- We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code detail: type: string description: Safe user-facing error detail status: type: string description: HTTP status code as a string source: type: object description: Location of the invalid request value properties: pointer: type: string parameter: type: string header: type: string additionalProperties: false meta: type: object description: >- Error metadata. Public responses include supportId by default and may include allowlisted provider recovery metadata. properties: supportId: type: string description: Request/support ID for troubleshooting connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking provider: type: object properties: name: type: string enum: - plaid description: Provider that returned the underlying error errorCode: type: string description: Provider error code, when available errorType: type: string description: Provider error type, when available requestId: type: string description: Provider request ID for troubleshooting required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] components: securitySchemes: HTTPBearer: type: http scheme: bearer ````