Skip to main content
POST
Report a native (non-bridged) deposit your platform has already detected on one of its own deposit addresses.

Authorizations

X-Client-Secret
string
header
required

Contact Mesh to get client Secret

X-Client-Id
string
header
required

Contact Mesh to get client Id

Body

application/json

Request body for POST /api/v1/bridging/notify.

Reports a native (non-bridged) deposit the client has already detected on one of its own deposit addresses, so Mesh records it, verifies it on chain and emits the same transfer webhooks a bridged deposit produces. One call per on-chain transaction.

Idempotent per transactionId scoped to userId and B2B client/environment: a retry with the same destination and transactionHash returns the original record. The same transactionId with a different destination or hash is a 400; a transactionHash already tracked for the same destination under another transactionId is a 409 (transferAlreadyRequested). The same hash crediting a different address is a separate deposit.

userId
string
required

Your platform's unique identifier for the end user who made this deposit. Combined with transactionId to enforce idempotency.

Required string length: 1 - 384
transactionId
string
required

Your platform's unique identifier for this deposit. One per on-chain transaction; re-submitting the same value with the same destination and hash returns the previously created record.

Required string length: 1 - 128
destination
object
required

Where the deposit landed: the network (CAIP-2 id), the asset symbol, and your platform's deposit address that received the funds. Mesh verifies the reported transaction against this destination.

transactionHash
string
required

Hash of the on-chain transaction that delivered the deposit to destination.address.

Required string length: 1 - 128
amount
string | null

Optional amount received, as a decimal string in destination.asset units (e.g. "125.5"). Informational: the on-chain credit is authoritative and is what the succeeded webhook carries; a differing value is logged for reconciliation but does not fail the deposit.

Maximum string length: 64

Response

Deposit recorded (or the original record returned on an idempotent retry); verification is in progress.

status
enum<string>
Available options:
ok,
serverFailure,
permissionDenied,
badRequest,
notFound,
conflict,
tooManyRequest,
locked,
unavailableForLegalReasons,
serviceUnavailable
message
string | null

A message generated by the API

displayMessage
string | null

User-friendly display message that can be presented to the end user

errorHash
string | null
read-only

An error grouping hash from string components and caller information. Used by bugsnag on FE for correct error grouping

teamCode
string | null
read-only

Opaque team code for error routing. Resolved from exception origin or caller file path via CODEOWNERS. Format: 2-character code (e.g., "7K", "M2"). Use for alerting/routing, not display.

errorType
string | null

Strictly-typed error type that is explaining the reason of an unsuccessful status of the operation. All possible error types are available in the documentation.

errorData
unknown
content
object | null

Response body for POST /api/v1/bridging/notify.

Echoes the recorded deposit and the tracking IDs to correlate the succeeded / failed webhook Mesh sends once the reported transaction has been verified on chain (or could not be by expirationTime). This endpoint does not return transfer status.