# DobProtocol — Full API Reference

> Infrastructure layer for tokenized real-world assets (RWA). Fractional physical asset ownership — verified on-chain.

## Base URL

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

## Authentication

All requests require an API key in the `X-API-Key` header.

```
X-API-Key: dob_ak_your_key_here
```

Keys are scoped:
- **read** — Pool discovery, portfolio queries, webhook management
- **trade** — Marketplace operations, crowdfunding contributions

To create an API key, authenticate with a wallet signature to get a JWT, then:

```
POST /auth/keys
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "label": "my-trading-bot",
  "scopes": ["read", "trade"]
}
```

## Rate Limiting

60 requests per minute per API key. Response headers:
- `X-RateLimit-Limit: 60`
- `X-RateLimit-Remaining: 57`
- `X-RateLimit-Reset: 1710000060`

## Response Format

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

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

## Supported Networks

| Network           | ID    |
|--------------------|-------|
| Stellar Mainnet    | 10    |
| Stellar Testnet    | 9     |
| Ethereum Mainnet   | 1     |
| Base Mainnet       | 8453  |
| Base Sepolia       | 84532 |
| Polygon Mainnet    | 137   |
| Arbitrum           | 42161 |

---

## Pools API

### GET /pools — List pools

Search and filter distribution pools.

**Query parameters:**
- `search` (string) — Pool name or ticker
- `network_id` (integer) — Network filter
- `access_type` (string) — `rtj` (airdrop), `p` (buy), `qr`, `stk` (staking)
- `sort` (string) — `created_desc`, `created_asc`, `apr_desc`, `apr_asc`, `members_desc`, `members_asc`
- `page` (integer, default: 1)
- `limit` (integer, default: 20, max: 100)

**Response data:** Array of `{ address, name, ticker, network_id, estimated_apr, member_count, max_participants, token_to_distribute, created_at }`

### GET /pools/featured — Featured pools

Curated pools. Optional `network_id` filter. Returns pools with `featured_reason` field.

### GET /pools/crowdfunding — Active crowdfunding

Optional query params: `network_id`, `sort` (`deadline_asc`, `deadline_desc`, `progress_desc`).

Returns pools with: `target_amount`, `raised_amount`, `progress_percent`, `contributor_count`, `deadline`, `payment_token`, `is_active`.

### GET /pools/{address} — Pool details

**Path param:** `address` (string, required)
**Query param:** `network_id` (integer, required if multi-network)

Returns full pool detail including `creator_address`, `distribution_config` (min_interval_seconds, claim_delay_seconds, round_expiry_seconds), `next_distribution`, `allow_entry`.

### GET /pools/{address}/members — Pool members

Paginated. Returns: `user_address`, `shares`, `participation_percent`, `joined_at`.

### GET /pools/{address}/distributions — Distribution history

Filter by `status`: `completed`, `pending`, `expired`. Paginated.

Returns: `round_id`, `token`, `total_amount`, `amount_per_share`, `total_claimed`, `claim_count`, `claimable_from`, `expires_at`.

### GET /pools/{address}/events — Pool events

Filter by `event_type`: `init`, `distribute`, `claim`, `transfer_shares`, `withdraw`, `lock`, `set_admin`. Paginated.

Returns: `event_type`, `transaction_hash`, `from_address`, `to_address`, `amount`, `token`, `date`, `description`.

---

## Marketplace API

### GET /marketplace/listings — All active listings

**Query parameters:**
- `network_id` (integer, required)
- `payment_token` (string) — Filter by token symbol
- `sort` (string) — `created_desc`, `created_asc`, `price_asc`, `price_desc`
- `page`, `limit`

**Response data:** Array of `{ sale_address, pool_address, pool_name, pool_ticker, network_id, seller_address, shares_amount, price_per_share, total_price, payment_token, payment_token_address, is_active, created_at }`

### GET /marketplace/listings/{poolAddress} — Pool listings

Active listings for a specific pool. Requires `network_id`. Sort: `price_asc`, `price_desc`, `created_desc`.

### GET /marketplace/stats/{poolAddress} — Pool marketplace stats

Returns: `floor_price`, `highest_price`, `payment_token`, `active_listings`, `total_shares_listed`, `volume_24h`, `volume_7d`, `volume_30d`, `total_volume`, `total_sales`.

### POST /marketplace/prepare-buy — Prepare buy transaction

All trade operations use a **prepare/submit** pattern to keep private keys secure.

```json
{
  "listing_id": "SALE_abc123...",
  "amount": 100,
  "network_id": 10
}
```

Returns unsigned XDR transaction (expires in 10 minutes) with `transaction_details`.

### POST /marketplace/submit-buy — Submit signed buy

```json
{
  "signed_xdr": "AAAAAgAAAA...",
  "network_id": 10
}
```

Returns: `transaction_hash`, `listing_id`, `shares_bought`, `total_cost`, `payment_token`, `stellar_explorer_url`.

### POST /marketplace/prepare-list — List shares for sale

```json
{
  "pool_address": "POOL_...",
  "shares_amount": 50,
  "price_per_share": "1.50",
  "payment_token": "USDC",
  "network_id": 10
}
```

### POST /marketplace/submit-list — Submit list transaction

```json
{ "signed_xdr": "...", "network_id": 10 }
```

### POST /marketplace/prepare-cancel — Cancel listing

```json
{ "listing_id": "SALE_...", "network_id": 10 }
```

### POST /marketplace/submit-cancel — Submit cancel transaction

```json
{ "signed_xdr": "...", "network_id": 10 }
```

---

## Webhooks API

Max 5 webhooks per API key. HMAC-SHA256 signature verification.

### POST /webhooks — Register webhook

```json
{
  "url": "https://your-server.com/dob-events",
  "events": ["distribution_created", "marketplace_sale_completed"],
  "secret": "your_webhook_secret_min_16_chars"
}
```

### GET /webhooks — List all webhooks

Returns webhook objects with `failure_count` and `last_triggered_at`.

### PUT /webhooks/{id} — Update webhook

All fields optional: `url`, `events`, `secret`, `is_active`.

### DELETE /webhooks/{id} — Delete webhook

### POST /webhooks/{id}/test — Test webhook delivery

Returns: `delivery_status`, `response_code`, `response_time_ms`.

### Event Types

- `distribution_created` — New distribution round started
- `claim_available` — Tokens ready to claim
- `shares_transferred` — Shares moved between addresses
- `pool_created` — New pool deployed
- `marketplace_listing_created` — New listing posted
- `marketplace_sale_completed` — Trade executed
- `crowdfunding_finalized` — Crowdfunding target reached
- `crowdfunding_failed` — Crowdfunding deadline passed without meeting target

### Webhook Delivery

Headers sent with each event:
- `Content-Type: application/json`
- `X-Dob-Signature` — HMAC-SHA256 of body using your secret
- `X-Dob-Event` — Event type
- `X-Dob-Delivery` — Unique delivery ID
- `X-Dob-Timestamp` — Unix timestamp

Must return 2xx within 10 seconds. Retry: exponential backoff (1m, 5m, 30m, 2h, 12h). Auto-deactivates after 5 consecutive failures.

---

## Core Products

- **Token Studio** — Create distribution pools, manage investor access, configure share structures. https://home.dobprotocol.com
- **DobValidator** — AI-powered asset verification using TRUFA scoring (IoT hardware, firmware integrity, operational readiness). https://validator.dobprotocol.com
- **DobDex** — Zero-slippage DEX using node-based liquidity for RWA tokens. https://dex.dobprotocol.com
- **DobLink** — Embeddable investment widget for asset owner websites. https://link.dobprotocol.com

## Pipeline

Verify → Tokenize → Distribute → Trade

## Links

- Website: https://dobprotocol.com
- Documentation: https://docs.dobprotocol.com
- Agent API Reference: https://docs.dobprotocol.com/agent-api
- OpenAPI Spec: https://dobprotocol.com/.well-known/openapi.json
- MCP Manifest: https://dobprotocol.com/.well-known/mcp.json
- Blog: https://dobprotocol.com/blog
- Twitter: https://twitter.com/dobprotocol
- GitHub: https://github.com/DOBProtocol

## Categories

DeFi, tokenization, RWA, trading, DePIN, fractional ownership, yield