Manage your explorer account programmatically using the Account API.
Note: The Account API is actively developed. Watch the OpenScanAI GitHub organization for changelog and breaking-change announcements.
Base URL: https://xdcscan.io/account/api/v1
Step 1: Create an account
Sign up at xdcscan.io with an email address. Account features — watchlists, private tags, custom ABIs, and elevated API rate limits — are tied to your account.
Step 2: Create an API key
From Account → API keys, create a new key. You can also create one through the API once you have a session token:
curl -X POST https://xdcscan.io/account/api/v1/user/api-keys \ -H "Authorization: Bearer YOUR_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "my-bot"}'Response:
{ "id": "9f2b1c4e-7a3d-4c21-9e8f-1a2b3c4d5e6f", "name": "my-bot", "api_key": "osk_live_4f8c2e1a9b7d..."}Store the api_key securely — it is only shown once.
Step 3: Authenticate requests
Pass the key as a bearer token on every Account API request:
curl https://xdcscan.io/account/api/v1/user/info \ -H "Authorization: Bearer osk_live_4f8c2e1a9b7d..."The same key also raises your rate limit on the public REST API v2. See API Keys & Rate Limits.
Step 4: Watch an address
Add an address to your watchlist to receive notifications on its activity:
curl -X POST https://xdcscan.io/account/api/v1/user/watchlist \ -H "Authorization: Bearer osk_live_4f8c2e1a9b7d..." \ -H "Content-Type: application/json" \ -d '{ "address_hash": "0x1234567890abcdef1234567890abcdef12345678", "name": "Treasury wallet", "notification_settings": { "native": { "incoming": true, "outgoing": true }, "ERC-20": { "incoming": true, "outgoing": false }, "ERC-721": { "incoming": true, "outgoing": false } }, "notification_methods": { "email": true, "webhook": true } }'Step 5: Tag addresses privately
Private tags label addresses across the explorer UI — only you can see them:
curl -X POST https://xdcscan.io/account/api/v1/user/tags/address \ -H "Authorization: Bearer osk_live_4f8c2e1a9b7d..." \ -H "Content-Type: application/json" \ -d '{ "address_hash": "0x1234567890abcdef1234567890abcdef12345678", "name": "Treasury wallet" }'Step 6: Upload a custom ABI
For contracts that are not publicly verified, upload an ABI so the explorer decodes methods and events for your account:
curl -X POST https://xdcscan.io/account/api/v1/user/custom-abis \ -H "Authorization: Bearer osk_live_4f8c2e1a9b7d..." \ -H "Content-Type: application/json" \ -d '{ "contract_address_hash": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", "name": "MyContract", "abi": "[{\"type\":\"function\",\"name\":\"balanceOf\",\"inputs\":[{\"name\":\"account\",\"type\":\"address\"}],\"outputs\":[{\"name\":\"\",\"type\":\"uint256\"}],\"stateMutability\":\"view\"}]" }'Error handling
The Account API returns standard HTTP status codes with a JSON error body:
{ "message": "Invalid API key"}| Status | Meaning |
|---|---|
| 400 | Validation error — check the request body |
| 401 | Missing or invalid API key |
| 404 | Resource not found |
| 429 | Rate limit exceeded — back off and retry |
Next steps
- Quickstart — watch your first address in five calls
- API Reference — full endpoint catalog
- REST API v2 — public, unauthenticated chain data