Authentication

Important — No Version Prefix

All endpoints are under /api/agent/*. There is no version prefix. Do not use /v1/ in any path.

Quick Start (2 Steps)

Get an API key in 2 HTTP calls. All auth endpoints are under /api/agent/auth/.

Step 1: Get a Challenge

curl https://home.dobprotocol.com/api/agent/auth/challenge/YOUR_STELLAR_PUBLIC_KEY

Response:

{
  "success": true,
  "data": {
    "message": "DobProtocol Agent Auth\nAddress: GBDM6KR...\nNonce: a1b2c3d4-...\nTimestamp: 1710000000000",
    "expires_in": 300
  }
}

Step 2: Sign and Register

Sign the message with your Stellar secret key, then register:

curl -X POST https://home.dobprotocol.com/api/agent/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "GBDM6KRXXJHKVYFJPTPW3WBDKUYVCH7NNEI67DDCP7YX4UHX2GODPHGI",
    "signature": "3a4b5c6d7e8f...",
    "label": "my-defi-agent",
    "scopes": ["read"]
  }'

Response (201):

{
  "success": true,
  "data": {
    "wallet": "GBDM6KRXXJHKVYFJPTPW3WBDKUYVCH7NNEI67DDCP7YX4UHX2GODPHGI",
    "api_key": {
      "id": 1,
      "key": "dob_ak_7f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a",
      "key_prefix": "dob_ak_7f3a",
      "label": "my-defi-agent",
      "scopes": ["read"],
      "rate_limit_rpm": 60
    }
  },
  "message": "Agent registered. Store your API key securely — it cannot be retrieved again."
}

Store your API key

The full dob_ak_... key is returned only once. If you lose it, you must register again.

Step 3: Use Your API Key

Include the key in the X-API-Key header on all requests:

curl https://home.dobprotocol.com/api/agent/pools?network_id=10 \
  -H "X-API-Key: dob_ak_7f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a"

---

Complete Example (Python)

import requests
from stellar_sdk import Keypair

BASE = "https://home.dobprotocol.com/api/agent"

# 1. Generate a Stellar keypair (or use an existing one)
keypair = Keypair.random()
WALLET = keypair.public_key
print(f"Wallet: {WALLET}")
print(f"Secret: {keypair.secret}")  # Save this!

# 2. Get challenge
challenge = requests.get(f"{BASE}/auth/challenge/{WALLET}").json()
message = challenge["data"]["message"]

# 3. Sign the challenge
signature = keypair.sign(message.encode()).hex()

# 4. Register and get API key
reg = requests.post(f"{BASE}/auth/register", json={
    "wallet": WALLET,
    "signature": signature,
    "label": "my-agent",
    "scopes": ["read"]
}).json()
api_key = reg["data"]["api_key"]["key"]
print(f"API Key: {api_key}")  # Save this! Only shown once.

# 5. Use the API
pools = requests.get(f"{BASE}/pools",
    headers={"X-API-Key": api_key},
    params={"network_id": 10}
).json()
print(pools["data"])

Complete Example (JavaScript)

const StellarSdk = require('@stellar/stellar-sdk');

const BASE = 'https://home.dobprotocol.com/api/agent';

// 1. Generate keypair
const keypair = StellarSdk.Keypair.random();
const wallet = keypair.publicKey();

// 2. Get challenge
const challenge = await fetch(`${BASE}/auth/challenge/${wallet}`).then(r => r.json());
const message = challenge.data.message;

// 3. Sign
const signature = keypair.sign(Buffer.from(message)).toString('hex');

// 4. Register
const reg = await fetch(`${BASE}/auth/register`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ wallet, signature, label: 'my-agent', scopes: ['read'] })
}).then(r => r.json());
const apiKey = reg.data.api_key.key;

// 5. Use the API
const pools = await fetch(`${BASE}/pools?network_id=10`, {
  headers: { 'X-API-Key': apiKey }
}).then(r => r.json());
console.log(pools.data);

---

API Key Details

Key Format

dob_ak_ + 64 hexadecimal characters

Scopes

Scope	Permissions
read	Pool discovery, portfolio queries, marketplace listings (read-only), webhook management
trade	Marketplace operations (buy, list, cancel), crowdfunding contributions

Recommended configurations:

Use Case	Scopes
Dashboard / monitoring	["read"]
Trading bot	["read", "trade"]

Rate Limiting

Each API key is limited to 60 requests per minute. Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1710000060

Security

• API keys are hashed with SHA-256 before storage — DobProtocol never stores your key in plaintext.
• Keys are bound to the wallet address that created them.
• Treat API keys like passwords. Do not commit them to version control.

---

Advanced: JWT Key Management

For human users who already have accounts via the DobProtocol UI, API keys can also be managed using JWT tokens obtained through the standard wallet login flow. See API Keys for JWT-based key management endpoints.

Security Best Practices

1. Use minimum required scopes. If your application only reads data, create a key with ["read"] only.
2. Rotate keys regularly. Use the key rotation endpoint to get a new key without downtime.
3. Store keys in environment variables or a secrets manager. Never hardcode them.
4. Revoke compromised keys immediately using the revoke endpoint.
5. Use separate keys for separate services. This limits blast radius if one key is compromised.