External wallet monitoring

Register an address your organization already owns when Relay should track token deposits or withdrawals and emit signed wallet events. This API does not create the wallet or expose its private key.

External wallet monitoring is different from customer wallets: it observes an existing organization address and does not run the customer-wallet fee and automatic per-customer settlement workflow.

Check whether a wallet exists#

GET /wallet/organization/external-wallet?address={address}&network={network}

Query field	Type	Required	Description
`address`	string	yes	Exact wallet address.
`network`	string	yes	Enabled network. New registrations currently accept `tron` or `solana`.

bash

curl --get \
  --url https://bridge.relayfinance.io/wallet/organization/external-wallet \
  --header 'accesskey: YOUR_ORGANIZATION_API_KEY' \
  --data-urlencode 'address=TQ9ExampleAddress' \
  --data-urlencode 'network=tron'

json

{
  "success": true,
  "data": {
    "exists": true,
    "wallet": {
      "id": "wallet_example",
      "address": "TQ9ExampleAddress",
      "network": "tron",
      "source": "external",
      "eventSubscriptions": []
    }
  },
  "meta": {
    "requestId": "627cd68a-c806-4ed8-9a83-fb1a68dfec5d"
  }
}

When no matching wallet belongs to the organization, exists is false and wallet is null.

Register a wallet#

POST /wallet/organization

Returns HTTP 200 OK with the saved wallet and its event subscriptions.

Field	Type	Required	Description
`address`	string	yes	Existing organization-controlled address.
`network`	string	yes	`tron` or `solana` for new work.
`events`	array	no	Deposit or withdrawal subscriptions. An empty list registers without notifications.
`events[].eventType`	string	yes	`deposit` or `withdrawal`.
`events[].network`	string	yes	Must match the wallet network.
`events[].token`	string	yes	Token symbol configured on the selected network.
`events[].requiredBlockConfirmation`	number	no	Non-negative confirmation threshold. Relay applies its configured default when omitted.

json

{
  "address": "TQ9ExampleAddress",
  "network": "tron",
  "events": [
    {
      "eventType": "deposit",
      "network": "tron",
      "token": "USDT",
      "requiredBlockConfirmation": 20
    },
    {
      "eventType": "withdrawal",
      "network": "tron",
      "token": "USDT",
      "requiredBlockConfirmation": 20
    }
  ]
}

Each direction/network/token tuple must be unique. The service rejects an event whose network differs from the wallet network.

Replace event subscriptions#

PUT /wallet/organization/{walletId}/events

This operation replaces the complete subscription set for the wallet. Send every subscription that should remain active.

json

{
  "events": [
    {
      "eventType": "deposit",
      "network": "tron",
      "token": "USDC"
    }
  ]
}

The returned data.events array contains the persisted subscription records and effective requiredBlockConfirmation values.

Wallet webhook payload#

Subscribed confirmed activity produces wallet.deposit or wallet.withdrawal events under the wallet_event action.

json

{
  "id": "event_example",
  "type": "wallet.deposit",
  "schemaVersion": "1",
  "occurredAt": "2026-09-20T12:05:20.000Z",
  "resourceVersion": 4,
  "data": {
    "wallet": {
      "id": "wallet_example",
      "address": "TQ9ExampleAddress",
      "network": "tron"
    },
    "transaction": {
      "id": "transaction_example",
      "amount": "85.250000",
      "token": "USDT",
      "network": "tron",
      "transactionHash": "fe3ExampleHash",
      "blockConfirmations": 20,
      "requiredBlockConfirmation": 20,
      "direction": "deposit"
    }
  }
}

Common errors#

HTTP	Message	Cause
`400`	`Address and network are required`	Missing lookup query fields
`400`	`Wallet Already Exist`	The address/network is already registered globally
`400`	`Duplicate wallet event subscription`	Repeated direction/network/token tuple
`400`	`Event network … does not match wallet network …`	Subscription uses another network
`400`	`Invalid Wallet`	Wallet ID is absent or not owned by the organization