> ## 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 wallets > List all wallets for the authenticated party, including wallet type, default flag, balance, and receiving bank name when available. ## OpenAPI ````yaml /api-reference/openapi.json get /wallets 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: /wallets: get: tags: - Wallets summary: List wallets description: >- List all wallets for the authenticated party, including wallet type, default flag, balance, and receiving bank name when available. operationId: wallet.list parameters: - name: partyId in: query schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: Party ID for delegated wallet lookup 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: description: Resource type type: string enum: - wallet id: type: string pattern: ^wal_[0-9a-f]{32}$ description: Resource ID attributes: type: object properties: status: enum: - active - frozen - closed type: string description: Wallet readiness status walletType: enum: - standard - vault type: string description: >- Wallet kind: a spendable standard wallet or the vault isDefault: type: boolean description: >- Whether this wallet is the party's default for unnamed operations createdAt: anyOf: - type: string format: date-time - type: 'null' description: >- Wallet creation time; null when the upstream read omits it displayName: anyOf: - type: string - type: 'null' description: Human-readable wallet name, when set description: anyOf: - type: string - type: 'null' description: User-facing wallet description, when set balance: anyOf: - type: object properties: available: type: integer description: >- Amount currently available to spend or withdraw (cents) total: type: integer description: Total wallet ledger balance (cents) currency: enum: - USD type: string description: Currency code required: - available - total - currency additionalProperties: false title: PublicWalletBalanceAttributes - type: 'null' description: >- Wallet ledger balance; null when the balance read failed transiently claims: type: object properties: amount: type: integer description: >- Total unclaimed product-payment amount (cents) count: type: integer description: Number of unclaimed product payments required: - amount - count additionalProperties: false title: WalletClaims description: Claimable payment totals depositInstructions: anyOf: - type: object properties: bankName: type: string description: Name of the receiving bank required: - bankName additionalProperties: false title: PublicDepositInstructionsAttributes - type: 'null' description: >- ACH deposit-instruction metadata for this wallet, when available required: - status - walletType - isDefault - createdAt - displayName - description - balance - claims - depositInstructions additionalProperties: false title: WalletAttributes description: Resource attributes relationships: type: object properties: party: type: object properties: data: type: object properties: type: description: Resource type type: string enum: - party id: type: string required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier required: - data additionalProperties: false title: ToOneRelationship description: Party that owns the wallet required: - party additionalProperties: false title: WalletRelationships description: Resource relationships required: - type - id - attributes - relationships additionalProperties: false title: WalletResource 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 title: WalletListMeta required: - data - meta additionalProperties: false title: WalletListResponse examples: default: summary: Default value: data: - type: wallet id: wal_550e8400e29b41d4a716446655440000 attributes: status: active walletType: standard isDefault: true createdAt: '2026-01-04T15:30:00Z' displayName: Operating description: null balance: available: 120000 total: 125000 currency: USD claims: amount: 125000 count: 2 depositInstructions: bankName: Bridge Financial relationships: party: data: type: party id: pty_7c9e6679e29b41d4a716446655440001 - type: wallet id: wal_650e8400e29b41d4a716446655440000 attributes: status: active walletType: vault isDefault: false createdAt: '2026-01-04T15:30:00Z' displayName: Vault description: null balance: available: 500000 total: 500000 currency: USD claims: amount: 0 count: 0 depositInstructions: bankName: Bridge Financial relationships: party: data: type: party id: pty_7c9e6679e29b41d4a716446655440001 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 ````