> ## Documentation Index > Fetch the complete documentation index at: https://docs.mnai.com/llms.txt > Use this file to discover all available pages before exploring further. # List Beneficiary Instruments > Returns the payout instruments for a beneficiary belonging to the authenticated Meridian account, bank accounts and stablecoin wallets alike, discriminated by `type`. ## OpenAPI ````yaml /products/meridian-accounts/api-reference/meridian-accounts.json get /v1/beneficiaries/{beneficiaryId}/instruments openapi: 3.1.1 info: title: Meridian API version: '1.0' description: API documentation for Meridian services contact: name: Meridian url: https://mnai.com email: support@mnai.com license: name: Proprietary url: https://mnai.com servers: - url: https://sandbox-api.va.meridianpay.com description: Sandbox - url: https://api.va.mnai.com description: Production security: [] paths: /v1/beneficiaries/{beneficiaryId}/instruments: get: tags: - Beneficiaries summary: List Beneficiary Instruments description: >- Returns the payout instruments for a beneficiary belonging to the authenticated Meridian account, bank accounts and stablecoin wallets alike, discriminated by `type`. operationId: listBeneficiaryInstruments parameters: - name: X-Meridian-Api-Key in: header description: >- Server-to-server (HMAC) requests only. Partner API key issued by Meridian during provisioning. schema: type: string example: your-api-key - name: X-Meridian-Timestamp in: header description: >- Server-to-server (HMAC) requests only. Current time in milliseconds since the Unix epoch. Must be within 60 seconds of the request. schema: type: string example: '1749566400000' - name: X-Meridian-Program-Id in: header description: >- Server-to-server (HMAC) requests only. Identifies the program context for the request. schema: type: string example: your-program-id - name: X-Meridian-User-Id in: header description: >- Server-to-server (HMAC) requests only. Identifies the Meridian user targeted by the request. Required for MULTI_USER integrations; omit for SINGLE_USER. schema: type: string example: user_123 - name: beneficiaryId in: path description: >- ID of the beneficiary — the `id` returned by `POST /v1/beneficiaries` or `GET /v1/beneficiaries`. required: true schema: type: string responses: '200': description: The instruments for the beneficiary content: application/json: schema: $ref: '#/components/schemas/BeneficiaryInstrumentListResponse' examples: wallet_and_bank_instruments: $ref: >- #/components/examples/ListBeneficiaryInstrumentsWalletAndBank '400': description: The requested beneficiary identifier is invalid content: application/json: schema: $ref: '#/components/schemas/MeridianError' '401': description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/MeridianError' '403': description: >- The authenticated caller is not permitted: JWT scope missing, or the partner API key lacks entitlement, user ownership, or user-type match content: application/json: schema: $ref: '#/components/schemas/MeridianError' '404': description: The requested beneficiary was not found content: application/json: schema: $ref: '#/components/schemas/MeridianError' security: - meridian-account-jwt: [] - partner-api-key: [] components: schemas: BeneficiaryInstrumentListResponse: type: object title: Beneficiary Instrument List Response description: A list of beneficiary instruments required: - instruments properties: instruments: type: array description: The instruments for the beneficiary items: $ref: '#/components/schemas/BeneficiaryInstrument' MeridianError: type: object title: MeridianError description: >- Represents an error response from the Meridian API, including validation errors and an optional error code. required: - message properties: validationErrors: type: array description: >- An array of validation errors that occurred during the processing of the request. This field is optional and may be empty if there are no validation errors. items: $ref: '#/components/schemas/ValidationError' errorCode: type: string description: >- Machine-readable code identifying the failure. Absent when the failure is fully described by `validationErrors`. Clients should tolerate codes added in the future. enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - INVALID_REQUEST - INTERNAL_ERROR - INFORMATION_REQUEST_NOT_EDITABLE - INVALID_USER_TYPE - SINGLE_USER_KEY_NOT_ALLOWED - USER_ID_HEADER_REQUIRED - USER_ID_HEADER_NOT_ALLOWED - PDF_PAGE_LIMIT_EXCEEDED - PDF_PASSWORD_PROTECTED - PDF_UNREADABLE message: type: string description: >- A human-readable message describing the error. This field is required and should provide a clear explanation of the error that occurred. BeneficiaryInstrument: type: object title: Beneficiary Instrument description: >- A payout instrument registered for a beneficiary. `type` selects the variant: `BANK_ACCOUNT` for a bank account, `BLOCKCHAIN_WALLET` for a stablecoin wallet address. required: - type properties: type: type: string description: Instrument type discriminator enum: - BANK_ACCOUNT - EWALLET - BLOCKCHAIN_WALLET discriminator: propertyName: type mapping: BANK_ACCOUNT: $ref: '#/components/schemas/BankAccountInstrumentResponse' BLOCKCHAIN_WALLET: $ref: '#/components/schemas/WalletInstrumentResponse' ValidationError: type: object title: ValidationError description: >- Represents a validation error that occurred during the processing of a request to the Meridian API. One of the following types of validation errors may be present: InvalidFormat, InvalidValue, MissingValue, UnprocessableValue, UnexpectedVerificationError, MissingRequestBody, MissingPathParameter, MissingQueryParameter, or NotFound. Each validation error includes a reference to the field that caused the error and a message describing the error. required: - type properties: type: type: string description: Identifies which ValidationError this is. enum: - InvalidFormat - InvalidValue - MissingPathParameter - MissingQueryParameter - MissingRequestBody - MissingValue - NotFound - UnexpectedVerificationError - Unknown - UnprocessableValue discriminator: propertyName: type mapping: InvalidFormat: $ref: '#/components/schemas/InvalidFormat' InvalidValue: $ref: '#/components/schemas/InvalidValue' MissingPathParameter: $ref: '#/components/schemas/MissingPathParameter' MissingQueryParameter: $ref: '#/components/schemas/MissingQueryParameter' MissingRequestBody: $ref: '#/components/schemas/MissingRequestBody' MissingValue: $ref: '#/components/schemas/MissingValue' NotFound: $ref: '#/components/schemas/NotFound' UnexpectedVerificationError: $ref: '#/components/schemas/UnexpectedVerificationError' Unknown: $ref: '#/components/schemas/Unknown' UnprocessableValue: $ref: '#/components/schemas/UnprocessableValue' BankAccountInstrumentResponse: title: Bank Account Instrument Response description: A beneficiary bank account instrument allOf: - $ref: '#/components/schemas/BeneficiaryInstrument' - type: object required: - id - status - displayName - currency - mask - createdAt - updatedAt properties: id: type: string description: Unique identifier of the instrument example: uspi-01JMERINSTR001 status: type: string description: Lifecycle status of the instrument example: ACTIVE displayName: type: string description: Display name of the instrument currency: type: string description: Currency of the instrument example: GBP mask: type: string description: Masked account identifier example: '1234' createdAt: type: string description: Timestamp when the instrument was created example: '2026-04-30T14:00:00Z' format: date-time updatedAt: type: string description: Timestamp when the instrument was last updated example: '2026-04-30T14:00:00Z' format: date-time bankAccount: oneOf: - $ref: '#/components/schemas/BeneficiaryInstrumentBankAccount' - type: 'null' availableRails: type: array description: >- Rails this instrument can be paid over, as reported by the banking provider. An empty list means the rails are not known yet, not that the instrument cannot be paid. example: - SWIFT items: type: string WalletInstrumentResponse: title: Wallet Instrument Response description: A beneficiary blockchain wallet instrument allOf: - $ref: '#/components/schemas/BeneficiaryInstrument' - type: object required: - id - status - displayName - currency - mask - createdAt - updatedAt properties: id: type: string description: Unique identifier of the instrument example: uspay-01JMERINSTR002 status: type: string description: Lifecycle status of the instrument example: ACTIVE displayName: type: string description: Display name of the instrument currency: type: string description: Currency of the instrument example: USDC_ETH mask: type: string description: Masked address identifier example: 4c21 createdAt: type: string description: Timestamp when the instrument was created example: '2026-04-30T14:00:00Z' format: date-time updatedAt: type: string description: Timestamp when the instrument was last updated example: '2026-04-30T14:00:00Z' format: date-time wallet: oneOf: - $ref: '#/components/schemas/BeneficiaryInstrumentWallet' - type: 'null' availableRails: type: array description: The single chain this address is registered on example: - ETHEREUM items: type: string InvalidFormat: title: InvalidFormat description: The provided value exists, but its format is invalid for the field. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. InvalidValue: title: InvalidValue description: >- The provided value is syntactically valid, but not accepted for the field. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. MissingPathParameter: title: MissingPathParameter description: A required path parameter was not supplied. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. MissingQueryParameter: title: MissingQueryParameter description: A required query parameter was not supplied. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. MissingRequestBody: title: MissingRequestBody description: >- The request body is missing or does not contain the required non-null fields. allOf: - $ref: '#/components/schemas/ValidationError' - type: object properties: message: type: string description: A human-readable explanation of the validation failure. fieldRef: type: string description: The field or parameter that triggered the validation error. MissingValue: title: MissingValue description: A required value for the field was not provided. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. NotFound: title: NotFound description: The referenced principal object was not found. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. UnexpectedVerificationError: title: UnexpectedVerificationError description: A downstream verification step failed while checking the value. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. Unknown: title: Unknown description: >- A validation error occurred but the specific field could not be determined. allOf: - $ref: '#/components/schemas/ValidationError' - type: object properties: message: type: string description: A human-readable explanation of the validation failure. fieldRef: type: string description: The field or parameter that triggered the validation error. UnprocessableValue: title: UnprocessableValue description: The provided value cannot be processed into a valid result. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. BeneficiaryInstrumentBankAccount: type: object title: Beneficiary Instrument Bank Account description: Bank account detail properties: bankName: type: - string - 'null' description: Name of the bank iban: type: - string - 'null' description: International Bank Account Number (masked) swiftBic: type: - string - 'null' description: SWIFT / BIC code accountNumber: type: - string - 'null' description: Local account number (masked) BeneficiaryInstrumentWallet: type: object title: Beneficiary Instrument Wallet description: Wallet detail properties: address: type: - string - 'null' description: On-chain address (masked) example: 0x9f****4c21 examples: ListBeneficiaryInstrumentsWalletAndBank: value: instruments: - id: uspay-hjzngk997lxa9ujhzwuj1ggs status: ACTIVE displayName: Nimbus settlement wallet currency: USDC_ETH mask: 4c21 createdAt: '2026-09-09T20:39:33Z' updatedAt: '2026-09-09T20:39:33Z' wallet: address: 0x9f****4c21 availableRails: - ETHEREUM type: BLOCKCHAIN_WALLET - id: uspay-livtzlodxb14uii1nvphu2et status: ACTIVE displayName: Nimbus settlement wallet (Polygon) currency: USDC_POLY mask: 4c21 createdAt: '2026-09-09T20:39:40Z' updatedAt: '2026-09-09T20:39:40Z' wallet: address: 0x9f****4c21 availableRails: - POLYGON type: BLOCKCHAIN_WALLET - id: uspay-pzrxbd1856x0tyxmdrkzhhml status: ACTIVE displayName: Nimbus USD operating currency: USD mask: '3210' createdAt: '2026-09-09T20:49:08Z' updatedAt: '2026-09-09T20:49:08Z' bankAccount: bankName: JPMorgan Chase Bank, N.A. accountNumber: 9876****3210 availableRails: - ACH - WIRE type: BANK_ACCOUNT securitySchemes: meridian-account-jwt: scheme: bearer bearerFormat: JWT description: >- Bearer token authentication, for client-server calls. Send the access token issued by `POST /v1/auth/token` as `Authorization: Bearer {token}`. The token carries its own program and user context, so the `X-Meridian-*` headers are not required. See [Authentication](/products/meridian-accounts/guides/authentication-overview). type: http partner-api-key: name: X-Meridian-Signature in: header description: >- Meridian HMAC header authentication, for server-to-server calls. Required headers: - `X-Meridian-Api-Key` - `X-Meridian-Timestamp` - `X-Meridian-Program-Id` - `X-Meridian-User-Id` (MULTI_USER integrations only) - `X-Meridian-Signature` `X-Meridian-Signature` is the HMAC SHA-256 signature of the canonical request string, computed per request. See [Authentication](/products/meridian-accounts/guides/authentication-overview) for how to construct it. type: apiKey ````