Skip to main content

Notification Endpoints

Notification endpoints allow users to retrieve notifications for their accounts, enabling push notification features in frontend applications.

Get Account Notifications

Retrieves all notifications for a given account address. Endpoint: GET /accounts/{account}/notifications

Path Parameters

  • account (string, required): Ethereum wallet address to retrieve notifications for

Response

Returns an array of notification objects. Typical notification fields:
FieldTypeDescription
idstringUnique notification identifier
accountstringThe account address this notification is for
typestringType of notification (e.g., “order_filled”)
messagestringHuman-readable notification message
timestampstringISO 8601 timestamp when the notification was created
metadataobjectAdditional notification-specific data

Code Examples

curl "https://api.cow.fi/accounts/0x1234567890abcdef1234567890abcdef12345678/notifications"
const accountAddress = '0x1234567890abcdef1234567890abcdef12345678';
const response = await fetch(`https://api.cow.fi/accounts/${accountAddress}/notifications`);
const notifications = await response.json();
console.log(`Found ${notifications.length} notifications`);
import requests

account_address = '0x1234567890abcdef1234567890abcdef12345678'
response = requests.get(f'https://api.cow.fi/accounts/{account_address}/notifications')
notifications = response.json()
print(f"Found {len(notifications)} notifications")

Response Example

[
  {
    "id": "notif_abc123",
    "account": "0x1234567890abcdef1234567890abcdef12345678",
    "type": "order_filled",
    "message": "Your order has been filled",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "metadata": {
      "orderId": "0xabc...",
      "executedAmount": "1000000000000000000"
    }
  },
  {
    "id": "notif_def456",
    "account": "0x1234567890abcdef1234567890abcdef12345678",
    "type": "order_expired",
    "message": "Your order has expired",
    "timestamp": "2024-01-14T08:15:00.000Z",
    "metadata": {
      "orderId": "0xdef..."
    }
  }
]
Empty array if no notifications:
[]

Notes

CMS Requirement

The notifications endpoint requires CMS integration:
  • Environment variable CMS_ENABLED must be set to true
  • CMS_API_KEY must be configured

Supported Notification Types

TypeDescriptionTrigger
order_filledOrder successfully executedSettlement event detected
order_expiredOrder expired without executionOrder validity period ended
order_cancelledOrder cancelled by userCancellation transaction
order_partially_filledPartial fill occurredPartial settlement
insufficient_balanceInsufficient balance for orderPre-execution check
price_improvementBetter price achievedSurplus detected

Notification Channels

Users can subscribe to receive notifications via:
  • Telegram Bot: Real-time messages via Telegram
  • Web Push: Browser push notifications
  • Email: Email alerts (if configured)
  • Webhook: Custom webhook integrations

Caching

Notification responses are cached for 5 minutes (300 seconds):
Cache-Control: public, max-age=300

Testing Locally

# Start required services
docker-compose up -d queue db

# Run migrations
yarn migration:run

# Start notification producer
yarn producer

# In another terminal, start the API
yarn start

# Query notifications
curl http://localhost:3001/accounts/0x.../notifications

Sending Test Notifications

# Set your test account address
export POST_TO_QUEUE_ACCOUNT=0x79063d9173C09887d536924E2F6eADbaBAc099f5

# Run the test that sends a notification
nx test notification-producer --testFile=src/sendPush.test.ts --skip-nx-cache

Integration with Frontend

Polling Pattern:
// Poll for new notifications every 30 seconds
setInterval(async () => {
  const notifications = await fetch(
    `/accounts/${account}/notifications`
  ).then(r => r.json());
  displayNotifications(notifications);
}, 30000);
With Caching:
let lastFetch = 0;
let cachedNotifications = [];

async function getNotifications() {
  const now = Date.now();
  if (now - lastFetch < 300000) {
    return cachedNotifications;
  }
  cachedNotifications = await fetch(
    `/accounts/${account}/notifications`
  ).then(r => r.json());
  lastFetch = now;
  return cachedNotifications;
}

Error Handling

ScenarioResponseSolution
CMS disabledService unavailableEnable CMS configuration
Invalid address400 Bad RequestVerify address format
Database error500 Internal ErrorRetry with exponential backoff
No notificationsEmpty array []Normal response, no error

Best Practices

  1. Cache locally: Store notifications in frontend state to reduce requests
  2. Respect cache headers: Honor the 5-minute cache period
  3. Handle empty responses: Empty arrays are normal for accounts without notifications
  4. Display timestamps: Show when notifications were created
  5. Group by type: Consider grouping notifications by type in the UI
  6. Mark as read: Implement local read/unread state on the frontend
  7. Pagination: Implement client-side pagination for large notification lists
  8. Error handling: Gracefully handle API errors without breaking the UI
Last modified on March 4, 2026