Developer Guide

How AI Agents Subscribe to the BGeometrics Bitcoin API

This page explains the machine-to-machine subscription flow using Lightning Network payment, then API access using a Bearer token.

Discovery metadata: GET https://bitcoin-data.com/bguser/.well-known/ai-agent.json

Overview

An AI agent subscribes in 4 steps:

1) Start onboarding and create a Lightning invoice.

2) Pay the invoice via Lightning Network.

3) Poll subscription status until it becomes ACTIVE.

4) Use the returned API key as Authorization: Bearer ....

Step 1: Start onboarding

Send a request to the subscription intent endpoint:

POST https://bitcoin-data.com/bguser/api/agent/subscriptions/intents

{
  "agentName": "ExampleBot",
  "email": "examplebot@yourdomain.ai",
  "plan": "monthly",
  "callbackUrl": "https://agent.example.com/bgeometrics/events"
}

Optional header for safe retries:

Idempotency-Key: 3c6d5f88-4294-48d2-94ea-4c1a7cfbf3d1

Typical response fields:

client_id - technical username for the agent
api_key - token used later as Bearer
onboarding_id - payment identifier
status_url - endpoint to check activation
callback_url_registered - callback registration state
invoice.payment_request - Lightning invoice to pay

Legacy endpoint still available: /api/agent/onboarding/start

Step 2: Pay the Lightning invoice

The agent (or a user wallet connected to the agent) pays invoice.payment_request through a Lightning wallet.

After settlement, backend webhook/sync logic updates the account subscription.

Step 3: Poll status

Check status with:

GET https://bitcoin-data.com/bguser/api/agent/subscriptions/intents/{onboarding_id}

Possible values:

PENDING_PAYMENT - invoice not settled yet
ACTIVE - subscription active, API calls enabled

Recommended polling interval: every 20-30 seconds.

Optional callback activation

If callbackUrl is provided in Step 1, BGeometrics sends subscription.activated after payment settlement.

Optional signature header: X-BG-Signature: sha256=... (HMAC SHA-256).

Step 4: Call BGeometrics API endpoints

Use the API key from onboarding as Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" \
https://bitcoin-data.com/v1/aviv

Best practices:

Store tokens in a secure secrets manager.
Do not expose tokens in frontend code or logs.
Retry gracefully when status is still PENDING_PAYMENT.

If onboarding is not activated after payment, verify webhook processing and invoice ID matching.

Example flow (pseudo logic)

start = POST https://bitcoin-data.com/bguser/api/agent/subscriptions/intents
while status != ACTIVE:
  status = GET https://bitcoin-data.com/bguser/api/agent/subscriptions/intents/{id}
  wait 20s
call protected API with Bearer api_key