curl --request POST \
--url https://sandbox-api.va.meridianpay.com/v1/beneficiaries/{beneficiaryId}/instruments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "BLOCKCHAIN_WALLET",
"displayName": "Nimbus settlement wallet (USDT)",
"walletAddress": "0x9f8B4a71Cc0Ed2b3F6a9E7c1D5b8A2f4E6c04C21",
"currency": "USDT_ETH",
"idempotencyKey": "e5f6a7b8-5555-6666-7777-88889999aaaa"
}
'{
"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"
}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.
curl --request POST \
--url https://sandbox-api.va.meridianpay.com/v1/beneficiaries/{beneficiaryId}/instruments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "BLOCKCHAIN_WALLET",
"displayName": "Nimbus settlement wallet (USDT)",
"walletAddress": "0x9f8B4a71Cc0Ed2b3F6a9E7c1D5b8A2f4E6c04C21",
"currency": "USDT_ETH",
"idempotencyKey": "e5f6a7b8-5555-6666-7777-88889999aaaa"
}
'{
"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"
}Authorizations
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.
Headers
Server-to-server (HMAC) requests only. Partner API key issued by Meridian during provisioning.
Server-to-server (HMAC) requests only. Current time in milliseconds since the Unix epoch. Must be within 60 seconds of the request.
Server-to-server (HMAC) requests only. Identifies the program context for the request.
Server-to-server (HMAC) requests only. Identifies the Meridian user targeted by the request. Required for MULTI_USER integrations; omit for SINGLE_USER.
Path Parameters
ID of the beneficiary — the id returned by POST /v1/beneficiaries or GET /v1/beneficiaries.
Body
Instrument to attach
- Bank Account Instrument Request
- Wallet Instrument Request
Bank account instrument to create for a beneficiary
Bank account to attach
Show child attributes
Show child attributes
Client-supplied idempotency key; retries with the same key are de-duplicated
"a1b2c3d4-1111-2222-3333-444455556666"
Instrument type discriminator
BANK_ACCOUNT, EWALLET, BLOCKCHAIN_WALLET Response
The newly created beneficiary instrument
- Bank Account Instrument Response
- Wallet Instrument Response
A beneficiary bank account instrument
Unique identifier of the instrument
"uspi-01JMERINSTR001"
Lifecycle status of the instrument
"ACTIVE"
Display name of the instrument
Currency of the instrument
"GBP"
Masked account identifier
"1234"
Timestamp when the instrument was created
"2026-04-30T14:00:00Z"
Timestamp when the instrument was last updated
"2026-04-30T14:00:00Z"
Instrument type discriminator
BANK_ACCOUNT, EWALLET, BLOCKCHAIN_WALLET Bank account detail
Show child attributes
Show child attributes
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.
["SWIFT"]