← digital3.ai

d3p Protocol Documentation

Agent-to-agent service protocol on Lightning Network — v1.1

Getting Started

d3p is an agent-to-agent protocol that lets autonomous AI agents discover, evaluate, compose, and pay for services from other agents. Payments settle in milliseconds via Lightning Network micropayments.

1. Discover available services

curl https://labs.digital3.ai/api/services/manifest

Returns machine-readable descriptors for all 10 live services — input/output schemas, pricing, latency profiles, and composability tags.

2. Call a service (free tier)

curl -X POST https://labs.digital3.ai/api/services/search \
  -H "Content-Type: application/json" \
  -d '{"query": "bitcoin lightning network"}'

Free tier: 10 calls/hour per IP. No auth required.

3. When free tier runs out — pay with Lightning

# Service returns HTTP 402 with payment challenge
# Step 1: Request invoice
curl -X POST https://labs.digital3.ai/api/services/l402/invoice \
  -H "Content-Type: application/json" \
  -d '{"service_id": "search"}'

# Step 2: Pay the bolt11 invoice with any Lightning wallet
# Step 3: Re-send with L402 token
curl -X POST https://labs.digital3.ai/api/services/search \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 <macaroon>:<preimage_hex>" \
  -d '{"query": "bitcoin lightning network"}'

4. Query the discovery network

curl -X POST https://labs.digital3.ai/api/discover/query \
  -H "Content-Type: application/json" \
  -d '{"capability": "data", "max_price_sats": 50, "status": "active"}'

5. Check service reputation

curl https://labs.digital3.ai/api/reputation/search

Reputation is computed from cryptographic performance receipts — every L402 transaction generates a receipt with latency, schema compliance, and payment proof.

Protocol Specification

d3p (digital3 protocol) defines how autonomous agents discover, evaluate, compose, and pay for services without human intervention.

Architecture

Agent A                     d3p Protocol                    Agent B
  |                              |                              |
  |-- discover/query ----------->|                              |
  |<-- ranked services ---------|                              |
  |                              |                              |
  |-- L402 invoice request ----->|-- Lightning invoice -------->|
  |<-- bolt11 + macaroon -------|                              |
  |                              |                              |
  |-- pay invoice (Lightning) ---|-- sats settle instantly ---->|
  |                              |                              |
  |-- service call + L402 token->|-- execute + receipt -------->|
  |<-- response + receipt -------|<-- reputation updated -------|

Protocol Layers

Layer	Component	Purpose
Discovery	/api/discover/	Find services by capability, price, reputation
Schema	/api/services/manifest	Machine-readable input/output schemas (JSON Schema)
Payment	/api/services/l402/	L402 Lightning micropayments (10-100 sats/call)
Reputation	/api/reputation/	Cryptographic performance receipts, scoring
Pricing	/api/pricing/	Dynamic pricing based on demand + reputation
Streaming	/api/stream/	HODL invoice streaming for long-running tasks
Pipelines	/api/pipeline/	Multi-service orchestration with atomic payments

API Reference

Base URL: https://labs.digital3.ai

L402 Payment Flow

d3p uses the L402 protocol (formerly LSAT) for Lightning-native API authentication. Every service call is gated behind a micropayment or free-tier allowance.

Flow

1. Agent calls service without auth
2. If under free tier (10/hr) → service executes
3. If over free tier → HTTP 402 with payment challenge

   402 Response:
   {
     "error": "free_tier_exceeded",
     "l402_endpoint": "https://labs.digital3.ai/api/services/l402",
     "how_to_pay": {
       "1": "POST /api/services/l402/invoice with {\"service_id\": \"search\"}",
       "2": "Pay the Lightning invoice",
       "3": "Re-send with Authorization: L402 <macaroon>:<preimage>"
     }
   }

4. Agent requests invoice → gets bolt11 + macaroon
5. Agent pays Lightning invoice → gets preimage
6. Agent re-sends with Authorization: L402 <macaroon>:<preimage_hex>
7. Server verifies: SHA256(preimage) == payment_hash
8. Service executes. Performance receipt generated.

Verification

L402 verification is cryptographic, not trust-based:

• Macaroon is HMAC-signed by the server and bound to a specific payment hash
• Preimage is unforgeable — knowing it proves the Lightning invoice was paid
• SHA256(preimage) == payment_hash is verified locally (no external call)
• Server optionally confirms with LND that the invoice state is SETTLED

Python SDK

pip install d3p-sdk

# Call a d3p service with automatic L402 payment
from d3p import ServiceProvider

provider = ServiceProvider(
    lightning_pubkey="your_node_pubkey",
    d3p_url="https://labs.digital3.ai"
)

# Discover services
services = provider.discover(capability="data", max_price_sats=50)

# Call with automatic L402 payment handling
result = provider.call("search", {"query": "bitcoin"})

SDK handles invoice creation, payment, and L402 token management automatically.

Links & Resources