Agent API

The DobProtocol Agent API enables AI agents, trading bots, and automated workflows to programmatically interact with the DobProtocol ecosystem. Discover distribution pools, trade shares on the marketplace, contribute to crowdfunding campaigns, and receive real-time webhook notifications -- all through a RESTful interface.

Base URL:

https://home.dobprotocol.com/api/agent

Important — No Version Prefix

All endpoints are under /api/agent/*. There is no version prefix. Do not use /v1/ in any path. For example: GET /api/agent/pools — not GET /api/agent/v1/pools.

Key Capabilities

Capability	Description
Pool Discovery	Search and filter pools by network, access type, and more
Portfolio Tracking	Query holdings, positions, and distribution schedules
Marketplace Trading	List shares for sale, buy listings, cancel orders
Crowdfunding	Contribute to active crowdfunding pools
Webhooks	Receive real-time notifications for on-chain events

Authentication

Get an API key in 2 calls — all under /api/agent/auth/:

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

# 2. Sign and register → returns your API key
curl -X POST https://home.dobprotocol.com/api/agent/auth/register \
  -H "Content-Type: application/json" \
  -d '{"wallet": "G...", "signature": "...", "label": "my-agent", "scopes": ["read"]}'

# 3. Use it
curl https://home.dobprotocol.com/api/agent/pools \
  -H "X-API-Key: dob_ak_your_key_here"

Scopes: read (pool discovery, portfolio, webhooks) | trade (marketplace, crowdfunding)

See Authentication for full details and code examples.

Response Format

All endpoints return a consistent JSON envelope.

Successful Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 142
  }
}

The meta field is included on paginated endpoints and omitted on single-resource responses.

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid or has been revoked."
  }
}

See Errors for the full list of error codes.

Rate Limiting

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

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

See Rate Limiting for details and how to request higher limits.

Quick Start

1. Get a challenge and register

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

# 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": "G...", "signature": "hex_signed_challenge", "label": "my-bot", "scopes": ["read", "trade"]}'

Save the returned dob_ak_... key — it is only shown once.

3. Discover pools

curl https://home.dobprotocol.com/api/agent/pools?network_id=10&sort=apr_desc&limit=5 \
  -H "X-API-Key: dob_ak_your_key_here"

4. Buy shares on the marketplace

# Prepare the transaction (returns unsigned XDR)
curl -X POST https://home.dobprotocol.com/api/agent/marketplace/prepare-buy \
  -H "X-API-Key: dob_ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"listing_id": "SALE_abc123...", "amount": 100}'

# Sign the XDR locally with your Stellar secret key, then submit
curl -X POST https://home.dobprotocol.com/api/agent/marketplace/submit-buy \
  -H "X-API-Key: dob_ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"signed_xdr": "AAAAAgAAAA..."}'

5. Set up a webhook

curl -X POST https://home.dobprotocol.com/api/agent/webhooks \
  -H "X-API-Key: dob_ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/dob-events",
    "events": ["distribution_created", "marketplace_sale_completed"],
    "secret": "your_webhook_secret"
  }'

Supported Networks

The Agent API supports all networks available on DobProtocol. Use the network_id parameter to filter by chain:

Network	network_id
Stellar Mainnet	10
Stellar Testnet	9
Ethereum Mainnet	1
Base Mainnet	8453
Base Sepolia (testnet)	84532
Polygon Mainnet	137
Arbitrum	42161

SDK and Libraries

While the Agent API is a standard REST API usable from any language, here is a minimal Python helper to get started:

import requests

class DobAgent:
    BASE_URL = "https://home.dobprotocol.com/api/agent"

    def __init__(self, api_key: str):
        self.session = requests.Session()
        self.session.headers.update({"X-API-Key": api_key})

    def get(self, path: str, params: dict = None) -> dict:
        resp = self.session.get(f"{self.BASE_URL}{path}", params=params)
        resp.raise_for_status()
        return resp.json()

    def post(self, path: str, json: dict = None) -> dict:
        resp = self.session.post(f"{self.BASE_URL}{path}", json=json)
        resp.raise_for_status()
        return resp.json()

# Usage
agent = DobAgent("dob_ak_your_key_here")
pools = agent.get("/pools", {"network_id": 10, "limit": 5})
print(pools["data"])

Next Steps

• Authentication -- Understand the JWT + API key auth flow
• API Keys -- Create and manage your API keys
• Pools -- Discover and query distribution pools
• Marketplace -- Trade shares programmatically
• Webhooks -- Receive real-time event notifications