Welcome to Databee. This guide will walk you through making your first queries to our Grid Capacity API, explaining the x402 payment protocol, and showing you how to integrate grid intelligence into your applications.
Whether you're building an AI agent that needs to find power for data centers, creating a site selection tool, or just exploring what's possible with grid data, this guide covers everything you need to know.
Prerequisites
Before you begin, you'll need:
- A crypto wallet with USDC on Base (for x402 payments)
- Basic familiarity with REST APIs and JSON
- An HTTP client (curl, Postman, or your preferred tool)
- Optional: An x402-compatible agent framework if you're building automated systems
If you're new to x402, don't worry—we'll explain how it works below.
Understanding x402 Payments
Databee uses the x402 payment protocol for micropayments. This is different from traditional API key authentication. Instead of subscribing to a plan, you pay per query using cryptocurrency.
Here's how it works:
1. Make a request to one of our endpoints without payment
2. Receive a 402 response with payment instructions (amount, recipient address, supported tokens)
3. Complete the payment on-chain (USDC on Base)
4. Retry your request with proof of payment in the headers
5. Receive your data
This model has several advantages:
- No subscriptions or commitments
- Pay only for what you use
- Works seamlessly with AI agents
- No API keys to manage
For AI agents and automated systems, x402 payments can be completed programmatically. Libraries are available for popular languages.
Your First Query: Capacity Scout
The Capacity Scout endpoint returns all substations in a region with available capacity above your specified threshold.
### Basic Request
curl -X POST https://api.databee.io/v1/capacity \
-H "Content-Type: application/json" \
-d '{
"region": "PJM",
"min_capacity_mw": 20
}'
### 402 Response
Since this request doesn't include payment, you'll receive a 402 response:
{
"error": "payment_required",
"amount": "50000000",
"token": "USDC",
"chain": "base",
"recipient": "0x...",
"memo": "capacity_scout_pjm_20mw",
"instructions": "Send USDC to recipient address, then retry with X-Payment-Proof header"
}
### Completing Payment
Using your wallet or an x402 library, send the specified amount to the recipient address. After confirmation (typically 1-2 blocks on Base), retry your request with the transaction hash:
curl -X POST https://api.databee.io/v1/capacity \
-H "Content-Type: application/json" \
-H "X-Payment-Proof: 0xabc123..." \
-d '{
"region": "PJM",
"min_capacity_mw": 20
}'
### Successful Response
{
"region": "PJM",
"query_params": {
"min_capacity_mw": 20
},
"timestamp": "2025-12-01T12:00:00Z",
"results": [
{
"substation_id": "PJM-SUB-12345",
"name": "Example Substation",
"location": {
"lat": 39.1234,
"lng": -77.5678,
"state": "VA",
"county": "Loudoun"
},
"capacity": {
"rated_mva": 200,
"current_load_mw": 120,
"available_mw": 75
},
"voltage_kv": 230,
"queue_depth": 2,
"utility": "Dominion Energy"
}
],
"total_results": 47
}
Query Parameters
### Capacity Scout Parameters
### Queue Intel Parameters
Queue Intel Endpoint
For deeper analysis, the Queue Intel endpoint returns the complete interconnection queue:
curl -X POST https://api.databee.io/v1/queue \
-H "Content-Type: application/json" \
-H "X-Payment-Proof: 0x..." \
-d '{
"region": "PJM",
"state": "VA",
"county": "Loudoun"
}'
### Response
{
"region": "PJM",
"location": {
"state": "VA",
"county": "Loudoun"
},
"timestamp": "2025-12-01T12:00:00Z",
"queue_entries": [
{
"queue_id": "AC2-123",
"queue_position": 1,
"project_name": "Example Data Center",
"project_type": "load",
"capacity_mw": 100,
"substation": "Loudoun 230kV",
"filed_date": "2023-06-15",
"status": "active",
"study_phase": "facilities",
"estimated_completion": "2026-Q2",
"developer": "Example Corp"
}
],
"total_entries": 47,
"summary": {
"total_mw_pending": 4200,
"avg_queue_age_months": 18,
"withdrawal_rate_12mo": 0.23
}
}
Webhook Integration
For real-time alerts, configure webhooks to notify you when conditions change:
### Registering a Webhook
curl -X POST https://api.databee.io/v1/webhooks \
-H "Content-Type: application/json" \
-H "X-Payment-Proof: 0x..." \
-d '{
"url": "https://your-server.com/webhooks/databee",
"events": ["capacity.available", "queue.updated"],
"filters": {
"regions": ["PJM", "ERCOT"],
"min_capacity_mw": 20
}
}'
### Event Types
### Webhook Payload
{
"event": "capacity.available",
"timestamp": "2025-12-01T14:30:00Z",
"data": {
"substation_id": "PJM-SUB-12345",
"previous_available_mw": 15,
"current_available_mw": 65,
"change_reason": "queue_withdrawal",
"withdrawn_project": "AC2-456"
},
"signature": "..."
}
Security Best Practices
### Verifying Webhook Signatures
All webhook payloads are signed with HMAC-SHA256. Verify signatures before processing:
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
### Payment Proof Validation
Our API validates payment proofs by:
1. Confirming the transaction exists on-chain
2. Verifying the amount matches the required payment
3. Checking the recipient address is correct
4. Ensuring the transaction has sufficient confirmations
5. Validating the memo matches your query
Payment proofs can only be used once. Attempting to reuse a proof will result in a 403 error.
Rate Limits
Even with valid payments, we enforce rate limits to ensure system stability:
Contact us for enterprise tier access if you need higher limits.
Error Handling
### Common Error Codes
### Retry Strategy
For production systems, implement exponential backoff:
async function queryWithRetry(params, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await makeQuery(params);
} catch (error) {
if (error.status === 429 || error.status >= 500) {
await sleep(Math.pow(2, i) * 1000);
continue;
}
throw error;
}
}
throw new Error('Max retries exceeded');
}
Next Steps
Now that you understand the basics:
1. Try the playground — Test queries interactively at databee.io/playground
2. Read the full API reference — Complete documentation at databee.io/docs
3. Join our Discord — Get help from the community and team
4. Build something cool — We'd love to see what you create
The grid data is there. Now go find the power.
