Overview

Lithic has created a new endpoint to create blockchain recipients — a customer's withdrawal wallet where stablecoin can be sent.

Create Blockchain Recipient registers that wallet against a Stablecoin-funded financial account and returns a token. Outbound stablecoin payments can then be sent to that destination.

New recipients are created with verification_state: PENDING and screened for compliance. Once screening clears the the recipient verification_state moves to ENABLED , and payments can be sent to it.

Companion endpoint: Get Blockchain Recipient returns the same object. Neither endpoint ever returns the address.

Details

Request

Response

There is no address field in the response — by design.

Verification lifecycle

1. POST /v1/blockchain_recipients creates the recipient as verification_state: PENDING, state: ENABLED.
2. The recipient is registered with the payment provider, which populates external_id.
3. The provider screens the wallet and reports the outcome. An active result moves the recipient to ENABLED; a denied result moves it to FAILED_VERIFICATION. Intermediate provider statuses are ignored — the recipient stays PENDING until screening actually resolves.
4. Poll GET /v1/blockchain_recipients/{token} until verification_state is ENABLED before initiating a payout.

Only ENABLED and FAILED_VERIFICATION are terminal; a recipient cannot be moved back to PENDING.

Idempotency and conflicts

Re-posting the same chain + address for the same program and the same account_token is treated as a replay: the existing recipient is returned with 200 OK instead of 201 Created, and no duplicate is made. Use the status code to tell a fresh registration from a replay.

How it's used with the payments endpoint

POST /v1/payments/stablecoin takes blockchain_recipient_token in place of any address field. Before placing a hold, the Ledger fetches the recipient from CIES, scoped to the calling instance, and requires both:

• verification_state == ENABLED
• state == ENABLED

If either check fails the payment is rejected with 400 Blockchain recipient is not enabled — this covers a still-PENDING recipient, one that failed screening, and one that has since been PAUSED or CLOSED. A token belonging to another program simply isn't found.

The recipient's chain drives the payout, so the payment request never restates it. The recipient's account_token records which account owns the wallet; it does not have to match the account funding the payout, and is not checked at payment time.

Payment retries are matched on the recipient too: replaying a stablecoin payment token with a different blockchain_recipient_token (or a different amount or linked hold) is rejected with 409 rather than treated as the same payment.

Sample request and response

Request

POST /v1/blockchain_recipients HTTP/1.1
Content-Type: application/json
x-instance-uuid: 8f1c0f9e-2f37-4a3e-9a2f-1d3c5b7a9e41

{
  "chain": "ETHEREUM",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "name": "Ada's treasury wallet",
  "owner": "Ada Lovelace",
  "owner_type": "INDIVIDUAL",
  "account_token": "3b9f6a52-7f1d-4c8e-b0a1-6c2d9e4f8b73"
}

Response — 201 Created

{
  "token": "c14e2a90-58d6-4a1b-9f77-0b3a2c6d8e51",
  "chain": "ETHEREUM",
  "address_tag": null,
  "external_id": null,
  "name": "Ada's treasury wallet",
  "owner": "Ada Lovelace",
  "owner_type": "INDIVIDUAL",
  "account_token": "3b9f6a52-7f1d-4c8e-b0a1-6c2d9e4f8b73",
  "program_id": "8f1c0f9e-2f37-4a3e-9a2f-1d3c5b7a9e41",
  "created": "2026-09-09T14:02:11Z",
  "updated": "2026-09-09T14:02:11Z",
  "state": "ENABLED",
  "verification_state": "PENDING"
}

Follow-up — once screening clears

GET /v1/blockchain_recipients/c14e2a90-58d6-4a1b-9f77-0b3a2c6d8e51 HTTP/1.1
x-instance-uuid: 8f1c0f9e-2f37-4a3e-9a2f-1d3c5b7a9e41

{
  "token": "c14e2a90-58d6-4a1b-9f77-0b3a2c6d8e51",
  "chain": "ETHEREUM",
  "address_tag": null,
  "external_id": "b6f4a1c2-9d38-4e57-8a10-2f5c7b9d3e64",
  "name": "Ada's treasury wallet",
  "owner": "Ada Lovelace",
  "owner_type": "INDIVIDUAL",
  "account_token": "3b9f6a52-7f1d-4c8e-b0a1-6c2d9e4f8b73",
  "program_id": "8f1c0f9e-2f37-4a3e-9a2f-1d3c5b7a9e41",
  "created": "2026-09-09T14:02:11Z",
  "updated": "2026-09-09T14:06:48Z",
  "state": "ENABLED",
  "verification_state": "ENABLED"
}

The recipient is now spendable:

POST /v1/payments/stablecoin
{
  "token": "d5a70c11-9b42-4f6a-8c3d-1e0f7a2b4c96",
  "type": "PAYMENT",
  "financial_account_token": "3b9f6a52-7f1d-4c8e-b0a1-6c2d9e4f8b73",
  "amount": 250000,
  "blockchain_recipient_token": "c14e2a90-58d6-4a1b-9f77-0b3a2c6d8e51"
}

Overview

Stablecoin payouts now send to a blockchain recipient — a customer's withdrawal wallet registered ahead of time — rather than to a raw address supplied at payment time.

POST /v1/blockchain_recipients registers that wallet against a financial account and returns a token. The token is the only handle used afterwards: POST /v1/payments/stablecoin accepts blockchain_recipient_token and never accepts an address, so the on-chain address is stored once, encrypted, and never travels through the Ledger.

Registration is not immediately spendable. A new recipient is created with verification_state: PENDING and is screened by the payment provider; only once screening clears and the recipient reaches ENABLED will a payout to it be accepted.

Companion endpoint: GET /v1/blockchain_recipients/{blockchain_recipient_token} returns the same object. Neither endpoint ever returns the address.

Details

Request

POST /v1/blockchain_recipients, with the caller's program supplied in the x-instance-uuid header.

Response

There is no address field in the response — by design.

How it's used with the Stablecoin Payments endpoint

Create Stablecoin Payment takes blockchain_recipient_token in place of any address field. This endpoint checks for the following on the token:

• verification_state == ENABLED
• state == ENABLED

Release Timeline

Available now: Sept 10, 2026.

User Impact

This change is additive only. Learn more about Stablecoin Payments via Stablecoin at Lithic.

If you have any questions or concerns, please contact us via the HELP link in your Lithic Dashboard.

The Lithic changelog has an RSS feed! To monitor for new update announcements, subscribe with your preferred RSS reader.