Listen Wallet
Subscribe on-chain addresses so the listener detects incoming deposits. Two endpoints are public (used by the listener worker); the rest require authentication.
List Addresses to Listen (Public)
Returns every address the listener should watch (subscriptions + active invoice addresses).
GET /api/v1/wallets/to-listen
Response 200
{
"message": "success list addresses to listen",
"data": [
{
"address": "0xabc...",
"network": "ethereum",
"expiresAt": "2026-01-01T00:00:00Z",
"bufferSeconds": 0,
"effectiveUntil": "2026-01-01T00:00:00Z"
}
]
}Get Listen Status (Public)
GET /api/v1/wallets/listen/:address/status
:address must be URL-encoded.
Response 200
{
"message": "success get address listen status",
"data": {
"address": "0xabc...",
"subscribed": true,
"expiresAt": "2026-01-01T00:00:00Z",
"bufferSeconds": 0,
"effectiveUntil": "2026-01-01T00:00:00Z"
}
}List Subscriptions
GET /api/v1/wallets/listen — requires authentication.
Response 200
{
"message": "success list address listen subscriptions",
"data": [
{
"address": "0xabc...",
"expiresAt": "2026-01-01T00:00:00Z",
"bufferSeconds": 0,
"effectiveUntil": "2026-01-01T00:00:00Z",
"isActive": true,
"createdAt": "2025-12-01T00:00:00Z",
"updatedAt": "2025-12-01T00:00:00Z"
}
]
}Subscribe an Address
POST /api/v1/wallets/listen/:address
Request Body (optional)
| Field | Type | Description |
|---|---|---|
expiresAt | string (RFC3339) or null | When to stop listening. null = listen forever |
bufferSeconds | int | Extra grace period after expiry (default 0) |
{
"expiresAt": "2026-01-01T00:00:00Z",
"bufferSeconds": 60
}| Code | Meaning |
|---|---|
| 403 | Wrong account type, or address not in your dedicated pool |
| 404 | Address not found |
| 409 | Subscription already exists |
Update a Subscription
PATCH /api/v1/wallets/listen/:address
{
"expiresAt": null
}| Code | Meaning |
|---|---|
| 404 | Subscription not found |
Unsubscribe
DELETE /api/v1/wallets/listen/:address
Response 200
{
"message": "success unsubscribe address listen"
}| Code | Meaning |
|---|---|
| 404 | Subscription not found |