> ## 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. # Add an Instrument to a Beneficiary > Attaches an additional payout instrument to an existing beneficiary for the authenticated Meridian account. A bank account (`BANK_ACCOUNT`) or a stablecoin wallet address (`BLOCKCHAIN_WALLET`). One wallet address may be registered once per supported currency, each as its own instrument. ## OpenAPI ````yaml /products/meridian-accounts/api-reference/meridian-accounts.json post /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: post: tags: - Beneficiaries summary: Add an Instrument to a Beneficiary description: >- Attaches an additional payout instrument to an existing beneficiary for the authenticated Meridian account. A bank account (`BANK_ACCOUNT`) or a stablecoin wallet address (`BLOCKCHAIN_WALLET`). One wallet address may be registered once per supported currency, each as its own instrument. operationId: createBeneficiaryInstrument 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 requestBody: description: Instrument to attach content: application/json: schema: $ref: '#/components/schemas/CreateBeneficiaryInstrumentRequest' examples: wallet_usdt_ethereum: $ref: >- #/components/examples/CreateInstrumentRequestWalletUsdtEthereum wallet_usdc_polygon: $ref: '#/components/examples/CreateInstrumentRequestWalletUsdcPolygon' us_bank_account: $ref: '#/components/examples/CreateInstrumentRequestUsBankAccount' required: true responses: '201': description: The newly created beneficiary instrument content: application/json: schema: $ref: '#/components/schemas/BeneficiaryInstrument' examples: wallet_usdt_ethereum: $ref: >- #/components/examples/CreateBeneficiaryInstrumentWalletUsdtEthereum us_bank_account: $ref: >- #/components/examples/CreateBeneficiaryInstrumentUsBankAccount '400': description: Invalid or malformed request body 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' '409': description: >- The wallet address is already registered as a payout destination for a different beneficiary of this account content: application/json: schema: $ref: '#/components/schemas/MeridianError' '503': description: >- A downstream provider was unreachable. The request was not applied and may be retried with the same idempotency key content: application/json: schema: $ref: '#/components/schemas/MeridianError' security: - meridian-account-jwt: [] - partner-api-key: [] components: schemas: CreateBeneficiaryInstrumentRequest: type: object title: Create Beneficiary Instrument Request description: >- A payout instrument to register 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/BankAccountInstrumentRequest' BLOCKCHAIN_WALLET: $ref: '#/components/schemas/WalletInstrumentRequest' 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' 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. BankAccountInstrumentRequest: title: Bank Account Instrument Request description: Bank account instrument to create for a beneficiary allOf: - $ref: '#/components/schemas/CreateBeneficiaryInstrumentRequest' - type: object required: - bankAccount - idempotencyKey properties: bankAccount: $ref: '#/components/schemas/BeneficiaryBankAccountInput' idempotencyKey: type: string description: >- Client-supplied idempotency key; retries with the same key are de-duplicated example: a1b2c3d4-1111-2222-3333-444455556666 WalletInstrumentRequest: title: Wallet Instrument Request description: Blockchain wallet instrument to create for a beneficiary allOf: - $ref: '#/components/schemas/CreateBeneficiaryInstrumentRequest' - type: object required: - displayName - walletAddress - currency - idempotencyKey properties: displayName: type: string description: Display label for the wallet example: Treasury unmanaged wallet D walletAddress: type: string description: Beneficiary's on-chain wallet address example: '0x9f8B4a71Cc0Ed2b3F6a9E7c1D5b8A2f4E6c04C21' currency: type: string description: >- Stablecoin currency of the destination. One of USDC_ETH, USDT_ETH, USDC_BASE, USDT_BASE, USDC_POLY, USDT_POLY. The network is derived from this value. example: USDC_ETH idempotencyKey: type: string description: >- Client-supplied idempotency key; retries with the same key are de-duplicated example: a1b2c3d4-1111-2222-3333-444455556666 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 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' BeneficiaryBankAccountInput: type: object title: Beneficiary Bank Account Input description: Bank account to attach required: - displayName - accountHolderName - currency - country - accountType properties: displayName: type: string description: Display name for the bank account example: Sherlock GBP account accountHolderName: type: string description: Name of the account holder example: Sherlock Holmes currency: type: string description: ISO 4217 currency code example: GBP country: type: string description: ISO 3166-1 alpha-2 country code example: GB accountType: type: string description: Bank account type example: CHECKING iban: type: - string - 'null' description: International Bank Account Number accountNumber: type: - string - 'null' description: Local account number swiftBic: type: - string - 'null' description: SWIFT / BIC code bankCode: type: - string - 'null' description: Local bank / routing code bankName: type: - string - 'null' description: Name of the bank bankAddress: oneOf: - $ref: '#/components/schemas/BeneficiaryAddress' - type: 'null' intermediaryBank: oneOf: - $ref: '#/components/schemas/IntermediaryBankInput' - type: 'null' 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 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. BeneficiaryAddress: type: object title: Beneficiary Address description: >- Address of the beneficiary's bank. Required by RouteFusion for non-US bank countries; a missing field is reported as a field-level validation error on submission. required: - addressLine1 - city - postalCode - countryCode properties: addressLine1: type: string description: First line of the address example: 221B Baker Street city: type: string description: City example: London postalCode: type: string description: Postal or ZIP code example: NW1 6XE countryCode: type: string description: ISO 3166-1 alpha-2 country code example: GB addressLine2: type: - string - 'null' description: Second line of the address stateProvince: type: - string - 'null' description: State or province IntermediaryBankInput: type: object title: Intermediary Bank Input description: >- Deprecated and ignored. RouteFusion generates the correspondent bank itself, so this field has no effect and will be removed. required: - bankName - routingCode properties: bankName: type: string description: Name of the intermediary bank example: JPMorgan Chase Bank, N.A. routingCode: type: string description: Routing code of the intermediary bank (e.g. US ABA) example: '021000021' examples: CreateInstrumentRequestWalletUsdtEthereum: value: type: BLOCKCHAIN_WALLET displayName: Nimbus settlement wallet (USDT) walletAddress: '0x9f8B4a71Cc0Ed2b3F6a9E7c1D5b8A2f4E6c04C21' currency: USDT_ETH idempotencyKey: e5f6a7b8-5555-6666-7777-88889999aaaa CreateInstrumentRequestWalletUsdcPolygon: value: type: BLOCKCHAIN_WALLET displayName: Nimbus settlement wallet (Polygon) walletAddress: '0x9f8B4a71Cc0Ed2b3F6a9E7c1D5b8A2f4E6c04C21' currency: USDC_POLY idempotencyKey: f6a7b8c9-6666-7777-8888-9999aaaabbbb CreateInstrumentRequestUsBankAccount: value: type: BANK_ACCOUNT idempotencyKey: a7b8c9d0-7777-8888-9999-aaaabbbbcccc bankAccount: displayName: Nimbus USD operating accountHolderName: Nimbus Settlement Ltd currency: USD country: US accountType: CHECKING accountNumber: '9876543210' bankCode: '021000021' bankName: JPMorgan Chase Bank, N.A. CreateBeneficiaryInstrumentWalletUsdtEthereum: value: id: uspay-wi9t4cyl9vwuqwudw2ld97bq status: ACTIVE displayName: Nimbus settlement wallet (USDT) currency: USDT_ETH mask: 4c21 createdAt: '2026-09-09T20:39:37Z' updatedAt: '2026-09-09T20:39:37Z' wallet: address: 0x9f****4c21 availableRails: - ETHEREUM type: BLOCKCHAIN_WALLET CreateBeneficiaryInstrumentUsBankAccount: value: 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 ````