Query Deposits and Users

The Reporting API lets your server read the Blink deposits flowing into your platform and look up the users behind them. Two read-only, paginated endpoints:

GET /v1/merchant-users — your Blink users, with each user’s total deposited and the embedded wallets they used. Look a user up by their embedded wallet to answer “has this user deposited with Blink before?”
GET /v1/merchant-deposits — settled deposits across both funding rails, filterable by user, chain, and date range, each with the on-chain transactions that credited your wallet.

Both are scoped entirely to your merchant account and return only the data you need to reconcile deposits — never the source wallet a user paid from, nor the transaction that funded a deposit, nor any personally identifying information.

On the testnet sandbox? Swap the host for https://api-sandbox.blink.cash.

Authentication

Every request is authenticated with a signed X-Merchant-Authorization header — the same identity credential used across the server-to-server API. See Merchant Authentication for how to build it.

curl https://api.blink.cash/v1/merchant-deposits \
  -H "X-Merchant-Authorization: $MERCHANT_AUTH"

Typical flow

The two endpoints compose. To check whether a returning user has deposited before and then pull their history:

Look the user up by their embedded wallet

GET /v1/merchant-users?embeddedWalletAddress=0x1a5F…&chainId=8453. An empty items array means they have never deposited to you. A hit returns their userId and total deposited.

Pull that user's deposits

Take the userId from step 1 and call GET /v1/merchant-deposits?userId=<userId>.

The userId is an opaque Blink-internal identifier — stable for a given user, safe to store, and the join key between the two endpoints.

Pagination

Both endpoints are cursor-paginated. Each response includes a nextCursor:

If nextCursor is a string, pass it back as ?cursor=<nextCursor> to fetch the next page.
If nextCursor is null, you have reached the last page.

Use limit (1–100, default 25) to set the page size. Treat the cursor as opaque — don’t parse or construct it. Deposits are returned newest-first; users are returned in a stable order suitable for walking the full list.

# First page
curl "https://api.blink.cash/v1/merchant-deposits?limit=50" \
  -H "X-Merchant-Authorization: $MERCHANT_AUTH"

# Next page
curl "https://api.blink.cash/v1/merchant-deposits?limit=50&cursor=eyJkIjoiMjAyNi0w…" \
  -H "X-Merchant-Authorization: $MERCHANT_AUTH"

List Blink users

GET https://api.blink.cash/v1/merchant-users Lists the users who have deposited to you, each with their total completed deposits and the distinct embedded wallets they deposited into. Supply embeddedWalletAddress (optionally narrowed by chainId) to return only the user owning that wallet.

Query parameters

Param	Type	Required	Description
`limit`	`integer`	No	Page size, 1–100. Default `25`.
`cursor`	`string`	No	Opaque cursor from the previous page’s `nextCursor`.
`embeddedWalletAddress`	`string`	No	Return only the user owning this embedded wallet address. Matched case-insensitively.
`chainId`	`integer`	No	Narrow the `embeddedWalletAddress` lookup to one chain (for example `8453`).

Response

{
  "items": [
    {
      "userId": "33333333-3333-3333-3333-333333333333",
      "amounts": {
        "total": {
          "amount": { "value": "610.00", "currency": "USD" },
          "count": 7
        },
        "completed": {
          "amount": { "value": "430.00", "currency": "USD" },
          "count": 5
        }
      },
      "firstDepositAt": "2026-01-02T18:30:00.000Z",
      "lastDepositAt": "2026-06-15T12:05:00.000Z",
      "embeddedWallets": [
        {
          "embeddedWalletAddress": "0x1a5FdBc891c5D4E6aD68064Ae45D43146D4F9f3a",
          "chain": { "chainId": 8453, "name": "Base" }
        }
      ]
    }
  ],
  "nextCursor": null
}

Field	Type	Description
`userId`	`string`	Opaque Blink-internal user id. Use as the `userId` filter on `/v1/merchant-deposits`.
`amounts.total.amount`	`object`	Sum of all this user’s deposits to you (every status — gross intended), as `{ value, currency }` where `value` is a decimal string.
`amounts.total.count`	`integer`	Total number of deposits this user has made to you (all statuses).
`amounts.completed.amount`	`object`	Sum of this user’s completed deposits to you (money actually received), same `{ value, currency }` shape.
`amounts.completed.count`	`integer`	Number of completed deposits this user has made to you.
`firstDepositAt` / `lastDepositAt`	`string`	ISO-8601 timestamps of the user’s first and most recent deposit.
`embeddedWallets`	`array`	Distinct embedded wallets this user deposited into, each with its `chain`.

amounts holds bucketed totals: total (all statuses, gross intended) and completed (money actually received). More status facets (for example a pending breakdown) can be added later without a breaking change.

List deposits

GET https://api.blink.cash/v1/merchant-deposits Lists settled deposits into your platform, newest first. Deposits that have not landed are never returned. Both funding rails create a record long before money moves — a wallet deposit the moment it is authorized, a manual transfer the moment a user picks a source — and most are abandoned. Those are intents, not deposits, so status on every item is always completed. Both funding rails appear in one list, distinguished by type:

blink — the user paid from a wallet they connected to the Blink widget.
manual_transfer — the user sent funds to a Blink deposit address themselves, typically a withdrawal from an exchange.

One consequence follows from manual_transfer deposits having no signed-in user: userId is always null for them, so filtering by userId returns blink deposits only — and /v1/merchant-users totals likewise cover blink deposits only.

Query parameters

Param	Type	Required	Description
`limit`	`integer`	No	Page size, 1–100. Default `25`.
`cursor`	`string`	No	Opaque cursor from the previous page’s `nextCursor`.
`userId`	`string` (uuid)	No	Return only this user’s deposits (the `userId` from `/v1/merchant-users`). Returns `blink` deposits only — see above.
`status`	`string`	No	Accepted only as `completed`, and only so existing callers keep working. Any other value returns `400` rather than an empty page — so `status=failed` can never be mistaken for “no failures”.
`chainId`	`integer`	No	Filter to one chain (for example `8453`).
`createdAfter`	`string`	No	ISO-8601; only deposits created at or after this time.
`createdBefore`	`string`	No	ISO-8601; only deposits created at or before this time.

Response

{
  "items": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "type": "blink",
      "userId": "33333333-3333-3333-3333-333333333333",
      "status": "completed",
      "amount": { "value": "50.00", "currency": "USD" },
      "chain": { "chainId": 8453, "name": "Base" },
      "token": {
        "symbol": "USDC",
        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      },
      "embeddedWalletAddress": "0x1a5FdBc891c5D4E6aD68064Ae45D43146D4F9f3a",
      "transactions": [
        {
          "hash": "0x81c3cc4b72aee96b86e6aea508e82ffe9665aef0192ce3119be315e4efa7c17d",
          "chain": { "chainId": 8453, "name": "Base" },
          "type": "settlement"
        }
      ],
      "createDate": "2026-06-15T12:05:00.000Z",
      "updateDate": "2026-06-15T12:06:30.000Z"
    }
  ],
  "nextCursor": "eyJkIjoiMjAyNi0wNi0xNVQxMjowNTowMC4wMDBaIiwiaWQiOiIxMTExMTExMS0xMTExLTExMTEtMTExMS0xMTExMTExMTExMTEifQ"
}

Field	Type	Description
`id`	`string`	Unique deposit id, unique across both rails.
`type`	`string`	`blink` or `manual_transfer` — which rail the deposit arrived over.
`userId`	`string \| null`	Opaque Blink-internal id of the depositing user (correlates to `/v1/merchant-users`). Always `null` for `manual_transfer`.
`status`	`string`	Always `completed` on this endpoint. Retained so the item shape stays stable if unsettled deposits are ever exposed.
`amount`	`object \| null`	USD amount as `{ value, currency }`, where `value` is a decimal string. Rarely `null` on a settled `manual_transfer` whose delivered amount could not be read back — a non-stablecoin or non-EVM destination, or a deposit predating that reading.
`chain`	`object`	The destination chain, `{ chainId, name }`.
`token`	`object`	The deposited token, `{ symbol, address }`. `symbol` is `null` if the token has left our registry.
`embeddedWalletAddress`	`string`	The embedded wallet address the funds landed in.
`transactions`	`array`	The deposit’s on-chain transactions, settlements first. See below.
`createDate` / `updateDate`	`string`	ISO-8601 timestamps.

`transactions[]`

Field	Type	Description
`hash`	`string`	The full transaction hash or signature — never truncated.
`chain`	`object \| null`	The chain this transaction is on, `{ chainId, name }` — the same shape as the deposit’s own `chain`, so one renderer handles both. Not always the same value: a refund lands on the chain the user deposited from. `null` only when the chain cannot be resolved.
`type`	`string`	`settlement` — credited your embedded wallet. `refund` — returned funds to the user.

Usually one element. A manual transfer sent straight to the deposit address can be funded by more than one transfer, and each one is its own settlement. Only transactions on your side of the deposit are listed. The transaction that funded a deposit is deliberately not exposed — it sits on the source chain and would identify the wallet your user paid from.

An empty transactions array does not mean the deposit has not settled. Reconcile on status, never on this array being non-empty.It is empty before a deposit settles, and also whenever the settlement transaction is not recoverable — for example when the routing provider reports success without returning a fill hash, when a same-chain same-token deposit’s funding transaction cannot be identified on-chain, or for deposits that completed before Blink began recording this. Deposits from before that point will show an empty array permanently.

Settled deposits only. Pending and failed deposits are not returned, so you never have to filter abandoned checkout attempts out of your reconciliation. If you need visibility into deposits that failed or were refunded, tell us — it is not exposed here today.

Response codes

Code	Meaning
`200`	OK.
`400`	Invalid query parameter or cursor, or a malformed `X-Merchant-Authorization` header.
`401 MERCHANT_AUTHORIZATION_MISSING`	The `X-Merchant-Authorization` header is missing.
`403 MERCHANT_NOT_REGISTERED` / `MERCHANT_NOT_ACTIVE`	The merchant is unknown or not yet approved.
`422`	The authorization envelope is stale, expired, or its signature is invalid. See Merchant Authentication.
`500`	Internal error.

Error shape

Errors use the standard Blink error envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameters."
  }
}

​Authentication

​Typical flow

​Pagination

​List Blink users

​Query parameters

​Response

​List deposits

​Query parameters

​Response

​transactions[]

​Response codes

​Error shape

Authentication

Typical flow

Pagination

List Blink users

Query parameters

Response

List deposits

Query parameters

Response

`transactions[]`

Response codes

Error shape