Onchain Trigger

Create a trigger address for a beneficiary. When you send tokens to this address, BLOX converts the tokens and pays the beneficiary. The deposit starts the transfer and also supplies the money for it. Thus, your prefund balance stays available for the payouts that you create. For the procedure, refer to Pay a beneficiary from a deposit.

Two records show one flow of money. The deposit is the tokens that arrive on-chain. The transfer is the bank payment that the deposit starts. The deposit shows the transfer in result.withdrawal. The transfer has its own status.

The trigger address accepts a deposit only from an allowed sender. Before you give the trigger address to a sender, allow that sender.

A read request must have the blox-api-key header. A write request must have the API key and an HTTP message signature. Every error response has the format { "code": "…", "message": "…", "requestId": "…" }. Use code to identify the error. Do not use message.

Create a deposit trigger address

Creates the trigger address for a beneficiary. The beneficiary must be active. A beneficiary has one trigger address for its lifetime. If you send this request again, BLOX returns the same address. Thus, an Idempotency-Key is not necessary.

The limit is 20 requests each minute. When you delete the beneficiary, BLOX deactivates its trigger address.

Success response (201)

{
  "address": "0x7c1a3e889d2b4f618a441f0b6d3c9a5588ab01cd",
  "network": "EVM",
  "destination": {
    "type": "BENEFICIARY",
    "id": "7c1a3e88-9d2b-4f61-8a44-1f0b6d3c9a55"
  }
}

The trigger address does not accept a deposit until you allow at least one sender. The same value is in autoWithdrawalAddress on the Beneficiary object.

List allowed senders

Returns the allowed senders of the beneficiary's trigger address. The oldest sender is first.

Success response (200)

[
  {
    "id": "3f8c1d02-5b47-4a6e-91cd-77e2b0a4f915",
    "address": "0x9a3f7c21b8e04d6f5a19c2e70b48d3f61a5e9d02",
    "label": "Treasury wallet",
    "active": true,
    "createdAt": "2026-08-07T09:31:05.000Z"
  }
]

The list also contains disabled senders. Disabled senders count toward the limit of 50 senders until you remove them.

If the beneficiary does not have a trigger address, BLOX returns 404 NOT_FOUND.

Allow a sender

Allows one sender address to start transfers to this beneficiary. A trigger address can have a maximum of 50 allowed senders.

Success response (201)

Returns the new allowed sender in the same format as List allowed senders.

Disable or re-enable a sender

Disables or enables an allowed sender. The sender stays in the list and keeps its label. A disabled sender does not start transfers. This change has an immediate effect. You can enable a disabled sender again.

Use this endpoint for a wallet that you will send from again. If you will not send from a wallet again, remove the sender. Only removal makes the place of the sender available in the limit of 50 senders.

Request body

Success response (200)

Returns the allowed sender in the same format as List allowed senders.

Remove an allowed sender

Removes the allowed sender. BLOX stops accepting deposits from that sender. The place of the sender in the limit of 50 senders becomes available. This change does not affect deposits that the sender sent before the removal. Sign only @method and @path. A Content-Digest header is not necessary.

Success response (200)

{ "success": true }

If the sender id is unknown or belongs to a different trigger address, BLOX returns 404 NOT_FOUND.

Get a deposit

Returns a deposit to a trigger address and the transfer that the deposit started. The deposit webhook event sends the same payload.

Use the endpoint of the channel that received the deposit. To get a deposit that BLOX paid into your own bank account, use GET /v1/wallet/deposits/{id}.

Success response (200)

{
  "id": "5e9d0273-8a41-4c62-b0f7-1d3e8c95a460",
  "txHash": "0x5d5355...103ee3",
  "logIndex": 12,
  "chainId": 1,
  "tokenId": "a71c4e08-2f96-4b3d-85ae-6c0f7d21b943",
  "amount": "100000",
  "from": "0x9a3f7c21b8e04d6f5a19c2e70b48d3f61a5e9d02",
  "status": "COMPLETED",
  "confirmations": 24,
  "triggerAddress": "0x7c1a3e889d2b4f618a441f0b6d3c9a5588ab01cd",
  "destination": {
    "type": "BENEFICIARY",
    "id": "7c1a3e88-9d2b-4f61-8a44-1f0b6d3c9a55",
    "name": "ADA LOVELACE"
  },
  "result": {
    "status": "COMPLETED",
    "statusReason": null,
    "withdrawal": {
      "id": "c4a80f13-6d29-4e75-83b1-9f0c2a7e5d68",
      "amount": "100000",
      "status": "COMPLETED",
      "refId": "FW-20260807-0001",
      "reference": "Invoice 4471",
      "createdAt": "2026-08-07T09:31:05.000Z",
      "updatedAt": "2026-08-07T09:34:22.000Z"
    }
  },
  "createdAt": "2026-08-07T09:30:44.000Z",
  "updatedAt": "2026-08-07T09:34:22.000Z"
}

amount and result.withdrawal.amount use different units. amount is in the smallest unit of the token. result.withdrawal.amount is in sen. Read each value from its own field.

A transfer is not in the GET /v1/payouts response. A transfer does not use your prefund balance.

If the deposit id is unknown, belongs to a different account, or identifies a deposit that BLOX paid into your own bank account, BLOX returns 404 NOT_FOUND.

Deposit status reason values

If result.status is not FAILED, result.statusReason is null. These values are different from the payout status reason values. The payout values apply to a payout that you create.

Older deposits can show inactive_beneficiary or missing_beneficiary_bank_details. These are the old names for inactive_destination and missing_destination_bank_details.

In all cases, the tokens stay credited to your wallet. If you can correct the cause, correct it and retry the deposit.

Check for a missed deposit

Tells BLOX to examine a transaction that BLOX did not detect. Use this endpoint if you sent tokens to a trigger address and you did not get a payout.deposit.updated webhook event.

This is the only endpoint that accepts a transaction hash. If BLOX already detected the transaction, the response contains the deposit ids. Use these ids with Get a deposit and Retry a deposit. The limit is 30 requests each minute.

Success response (201)

{
  "status": "ALREADY_DETECTED",
  "depositIds": ["5e9d0273-8a41-4c62-b0f7-1d3e8c95a460"]
}

Read status before you read depositIds. On QUEUED, an empty array means that the deposits do not exist yet. It does not mean that BLOX found no deposits. One transaction can pay more than one beneficiary. On QUEUED, wait for the webhook event. Do not send the request again.

Retry a deposit

Tries again to start a transfer for a credited deposit that did not start a transfer. Use this endpoint after you correct the cause. For example, allow the sender, activate the beneficiary again, or wait until the limit period resets.

You can send this request more than one time. If the deposit already has a transfer, the response contains that transfer. BLOX does not create a second transfer. The limit is 60 requests each minute.

Do not send a request body. Sign only @method and @path.

Success response (201)

Returns the deposit in the same format as Get a deposit. The response shows the deposit after the retry.

Webhook events

BLOX sends two webhook events about this flow to your PAYOUT webhook endpoint. A deposit starts the transfer. These webhook events tell you about each deposit and its transfer. The payout.created and payout.updated webhook events are for the payouts that you create with POST /v1/payouts.

For the envelope, signature verification, retries, and URL rules, refer to Payout Webhook Events and Webhooks.

payout.deposit.updated

{
  "id": "5e9d0273-...",
  "txHash": "0x5d5355...103ee3",
  "logIndex": 12,
  "chainId": 1,
  "tokenId": "a71c4e08-...",
  "amount": "100000",
  "from": "0x9a3f7c21b8e04d6f5a19c2e70b48d3f61a5e9d02",
  "status": "COMPLETED",
  "confirmations": 24,
  "triggerAddress": "0x7c1a3e889d2b4f618a441f0b6d3c9a5588ab01cd",
  "destination": { "type": "BENEFICIARY", "id": "7c1a3e88-...", "name": "ADA LOVELACE" },
  "result": { "status": "FAILED", "statusReason": "sender_not_allowed", "withdrawal": null },
  "createdAt": "2026-08-07T09:30:44.000Z",
  "updatedAt": "2026-08-07T09:34:22.000Z"
}

The fields are the same as in the REST response. For the full table, refer to GET /v1/payouts/deposits/{id}. For the reason values, refer to deposit status reason values.

BLOX sends this webhook event two times for each deposit. The status in the payload identifies the event:

Only COMPLETED means that the tokens are in your wallet. BLOX usually credits the tokens a few minutes after confirmation. On Ethereum, this takes longer when network fees are high.

A retry can send a PROCESSING event after the COMPLETED event for the same deposit. If your record of a deposit is COMPLETED, do not change it to a different status.

If BLOX refuses a deposit for a reason that you can correct, the COMPLETED event shows the reason. You can retry that deposit. BLOX also sends this webhook event for deposits on Solana. For Solana, txHash is the transaction signature (base58), and chainId is 101.

payout.withdrawal.updated

{
  "withdrawalId": "c4a80f13-...",
  "status": "COMPLETED",
  "statusReason": null,
  "amount": "100000",
  "refId": "FW-20260807-0001",
  "reference": "Invoice 4471",
  "destination": { "type": "BENEFICIARY", "id": "7c1a3e88-...", "name": "ADA LOVELACE" },
  "depositId": "5e9d0273-...",
  "createdAt": "2026-08-07T09:31:05.000Z",
  "updatedAt": "2026-08-07T09:34:22.000Z"
}

These transfers are different from payouts. A withdrawalId is not a payoutId. If you use a withdrawalId with GET /v1/payouts/{id}, BLOX returns 404.