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

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

The Agent API uses API key authentication. Include your key in the X-API-Key header with every request:

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

API keys are created and managed through JWT-protected endpoints. Each key has scoped permissions that control what operations it can perform:

• read -- Pool discovery, portfolio queries, webhook management
• trade -- Marketplace operations, crowdfunding contributions

See Authentication for the full auth flow, and API Keys for key management.

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 JWT token

Authenticate with your wallet to obtain a JWT, then use it to create an API key.

2. Create an API key

curl -X POST https://home.dobprotocol.com/api/agent/auth/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "my-trading-bot", "scopes": ["read", "trade"]}'

Save the returned 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