# 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](/docs/wallets/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 |