Oracle API
REST API for server-side Web of Trust queries. No extension required.
Public Servers
| Server | URL | Rate Limit |
|---|---|---|
| Primary | https://wot-oracle.dtonon.com | 60 req/min |
For higher rate limits or custom deployments, self-host the Oracle server.
Endpoints
GET
/healthCheck if the server is running and healthy.
Response
json
{
"status": "ok",
"version": "1.0.0"
}Example
terminal
$curl "https://wot-oracle.dtonon.com/health"
GET
/statsGet server statistics about the social graph.
Response
json
{
"total_users": 125000,
"total_follows": 2500000,
"last_updated": "2024-01-15T12:00:00Z",
"uptime": "5d 12h 30m"
}GET
/followsGet the follow list for a pubkey.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
pubkey | Yes | 64-character hex pubkey |
Response
json
{
"pubkey": "82341f...",
"follows": ["3bf0c6...", "fa984b...", "..."],
"count": 150
}Example
terminal
$curl "https://wot-oracle.dtonon.com/follows?pubkey=82341f..."
GET
/common-followsGet accounts that both pubkeys follow.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
pubkey1 | Yes | First pubkey |
pubkey2 | Yes | Second pubkey |
Response
json
{
"pubkey1": "82341f...",
"pubkey2": "3bf0c6...",
"common": ["fa984b...", "..."],
"count": 25
}GET
/pathGet the shortest path between two pubkeys.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
from | Yes | Source pubkey |
to | Yes | Target pubkey |
Response
json
{
"from": "82341f...",
"to": "3bf0c6...",
"path": ["82341f...", "fa984b...", "3bf0c6..."],
"hops": 2
}GET
/distanceGet the hop distance between two pubkeys.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
from | Yes | Source pubkey |
to | Yes | Target pubkey |
max_hops | No | Max hops to search (1-10, default: 4) |
Response
json
{
"from": "82341f...",
"to": "3bf0c6...",
"distance": 2,
"paths": 3,
"mutual": false
}Example
terminal
$curl "https://wot-oracle.dtonon.com/distance?from=82341f...&to=3bf0c6..."
POST
/distance/batchGet distances to multiple targets in a single request.
Request Body
json
{
"from": "82341f882b6eabcd2ba7f1ef90aad961cf074af15b9ef44a09f9d2a8fbfbe6a2",
"targets": ["3bf0c6...", "fa984b...", "..."]
}Response
json
{
"from": "82341f...",
"results": [
{
"to": "3bf0c6...",
"distance": 2,
"paths": 1,
"mutual": false
},
{
"to": "fa984b...",
"distance": 1,
"paths": 1,
"mutual": true
}
]
}Limit: Maximum 100 targets per request.
Example
terminal
$curl -X POST "https://wot-oracle.dtonon.com/distance/batch" \
$ -H "Content-Type: application/json" \
$ -d '{"from": "82341f...", "targets": ["3bf0c6...", "fa984b..."]}'
Error Handling
All endpoints return errors in a consistent format:
json
{
"error": "Invalid pubkey length: expected 64, got 32",
"code": "INVALID_PUBKEY_LENGTH"
}Error Codes
| Code | Description |
|---|---|
INVALID_PUBKEY_LENGTH | Pubkey must be 64 characters |
INVALID_PUBKEY_FORMAT | Pubkey must be hexadecimal |
INVALID_MAX_HOPS | max_hops must be 1-10 |
TOO_MANY_TARGETS | Max 100 targets in batch |
INTERNAL_ERROR | Server error |
HTTP Status Codes
- 200 - Success
- 400 - Validation errors (invalid pubkey, parameters)
- 429 - Rate limited (check
Retry-Afterheader) - 500 - Internal server error
Rate Limit Headers
All responses include rate limit information:
X-RateLimit-Limit- Requests per windowX-RateLimit-Remaining- Remaining requestsX-RateLimit-Reset- Seconds until reset