Skip to main content
Notifications are delivered through the Base App only. Users who interact with your app on other platforms will not receive notifications through this API.
The Notifications API lets you send in-app notifications to users who have pinned your app and opted in to notifications. Two REST endpoints handle the full workflow: fetch your audience’s wallet addresses, then send targeted or broadcast messages.

​
Prerequisites

  • A project on Base Dashboard with your app URL registered
  • An API key generated from Settings > API Key in your Base Dashboard project

​
Quick start

Both endpoints require your API key in the x-api-key header.
The notification endpoints share a rate limit of 10 requests per minute per IP. Requests to either endpoint count toward the same limit. Exceeding it returns a 429 Too Many Requests response.
Fetch the wallet addresses of users who have opted in to notifications for your app:
Get users with notifications enabled
curl "https://dashboard.base.org/api/v1/notifications/app/users?app_url=<your-app-url>&notification_enabled=true" \
  -H "x-api-key: <your-api-key>"
Response
{
  "success": true,
  "users": [
    { "address": "0xA11ce00000000000000000000000000000000000", "notificationsEnabled": true },
    { "address": "0xB0B0000000000000000000000000000000000000", "notificationsEnabled": true }
  ]
}
Send a notification to one or more of those addresses. The target_path sets the route within your app that opens when the user taps the notification:
Send a notification
curl -X POST "https://dashboard.base.org/api/v1/notifications/send" \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "app_url": "<your-app-url>",
    "wallet_addresses": ["<wallet-address>"],
    "title": "<title>",
    "message": "<message>",
    "target_path": "<target-path>"
  }'
Response
{
  "success": true,
  "results": [
    { "walletAddress": "0xA11ce00000000000000000000000000000000000", "sent": true }
  ],
  "sentCount": 1,
  "failedCount": 0
}

​
API reference

​
GET /v1/notifications/app/users

Returns users who have pinned your app, with optional filtering by notification opt-in status. Results are paginated. 
GET https://dashboard.base.org/api/v1/notifications/app/users

​
Query parameters

​
app_url
string
required
Your app URL as registered on the Base Dashboard.
​
notification_enabled
boolean
Set to true to return only users who have enabled notifications for your app.
​
cursor
string
Pagination cursor returned from a previous response. Omit for the first page.
​
limit
integer
Maximum users per page. Capped at 100.

​
Response

​
success
boolean
Whether the request succeeded.
​
users
array
Users who have pinned your app.
​
users[].address
string
The user’s wallet address.
​
users[].notificationsEnabled
boolean
Whether the user has enabled notifications for your app.
​
nextCursor
string
Cursor for the next page. Absent when no more results exist.

​
POST /v1/notifications/send

Sends an in-app notification to one or more wallet addresses. 
POST https://dashboard.base.org/api/v1/notifications/send

​
Request body

​
app_url
string
required
Your app URL as registered on the Base Dashboard.
​
wallet_addresses
string[]
required
Wallet addresses to notify. Minimum 1, maximum 1,000 per request.
​
title
string
required
Notification title. Maximum 30 characters.
​
message
string
required
Notification body text. Maximum 200 characters.
​
target_path
string
Path to open when the user taps the notification, such as /rewards. Must start with / if provided. Maximum 500 characters. Omit to open your app at its root URL.

​
Response

​
success
boolean
true only when every address in the request delivered successfully.
​
results
array
Per-address delivery status.
​
results[].walletAddress
string
The targeted wallet address.
​
results[].sent
boolean
Whether delivery succeeded for this address.
​
results[].failureReason
string
Present when sent is false. Possible values: user has not saved this app, user has notifications disabled.
​
sentCount
number
Total notifications delivered successfully.
​
failedCount
number
Total notifications that failed to deliver.

​
Errors

Both endpoints return the following errors:
StatusCodeCause
400Bad RequestPossible causes:
  • app_url is missing
  • title is missing or exceeds 30 characters
  • message is missing or exceeds 200 characters
  • wallet_addresses is missing or exceeds 1,000 addresses
  • target_path exceeds 500 characters or does not start with /
401UnauthorizedMissing or invalid API key.
403ForbiddenThe app_url does not belong to your project, or your project is not whitelisted for notifications.
404Not FoundThe project associated with your API key does not exist.
503Service UnavailableThe notification service is temporarily unavailable. Retry the request. Send endpoint only.

​
Batching and deduplication

Each request accepts up to 1,000 addresses. For larger audiences, split your address list across multiple requests. Duplicate addresses within a single request are deduplicated automatically. Identical notifications — same app URL, wallet address, title, message, and target path — sent within a 24-hour window are also deduplicated and return a success response without sending a duplicate push.