Portfolio

Portfolio endpoints return information about the wallet associated with your API key -- holdings across pools, individual positions, upcoming distributions, and transaction history.

All portfolio endpoints require an API key with the read scope.

Authentication: X-API-Key header (read scope)

All Holdings

Retrieve all pool holdings for the wallet associated with the API key.

GET /api/agent/portfolio/holdings

Query Parameters:

Parameter	Type	Default	Description
`network_id`	integer	--	Filter by network

curl:

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

Python:

import requests

resp = requests.get(
    "https://home.dobprotocol.com/api/agent/portfolio/holdings",
    headers={"X-API-Key": API_KEY},
    params={"network_id": 10}
)
holdings = resp.json()["data"]
for h in holdings:
    print(f"{h['pool_name']} ({h['pool_ticker']}): "
          f"{h['shares']} shares ({h['participation_percent']}%) - "
          f"Total earned: {h['total_earned']} {h['distribution_token']}")

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "pool_address": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
      "pool_name": "Solar Farm Alpha",
      "pool_ticker": "SFA",
      "network_id": 10,
      "chain_name": "Stellar Mainnet",
      "shares": 1500,
      "total_shares": 10000,
      "participation_percent": 15.0,
      "distribution_token": "USDC",
      "total_earned": "2287.50",
      "unclaimed_amount": "375.00",
      "unclaimed_rounds": 1,
      "estimated_apr": 12.5,
      "joined_at": "2026-02-20T14:00:00Z"
    },
    {
      "pool_address": "CA7QYNF7SOVZ4V4LXQHXWJQVGU3ZGR4A5OHCOQZSC7M2XZFKK67TYXZ",
      "pool_name": "Wind Turbine Collective",
      "pool_ticker": "WTC",
      "network_id": 10,
      "chain_name": "Stellar Mainnet",
      "shares": 500,
      "total_shares": 8000,
      "participation_percent": 6.25,
      "distribution_token": "USDC",
      "total_earned": "450.00",
      "unclaimed_amount": "0.00",
      "unclaimed_rounds": 0,
      "estimated_apr": 9.8,
      "joined_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Position in Specific Pool

Retrieve detailed position information for the wallet in a specific pool.

GET /api/agent/portfolio/holdings/:address

Path Parameters:

Parameter	Type	Description
`address`	string	Pool contract address

Query Parameters:

Parameter	Type	Default	Description
`network_id`	integer	--	Network ID

curl:

curl "https://home.dobprotocol.com/api/agent/portfolio/holdings/CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC?network_id=10" \
  -H "X-API-Key: dob_ak_your_key_here"

Python:

pool_address = "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
resp = requests.get(
    f"https://home.dobprotocol.com/api/agent/portfolio/holdings/{pool_address}",
    headers={"X-API-Key": API_KEY},
    params={"network_id": 10}
)
position = resp.json()["data"]
print(f"Shares: {position['shares']}")
print(f"Unclaimed: {position['unclaimed_amount']} {position['distribution_token']}")
print(f"Claimable rounds: {[r['round_id'] for r in position['claimable_rounds']]}")

Response (200 OK):

{
  "success": true,
  "data": {
    "pool_address": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
    "pool_name": "Solar Farm Alpha",
    "pool_ticker": "SFA",
    "network_id": 10,
    "shares": 1500,
    "total_shares": 10000,
    "participation_percent": 15.0,
    "distribution_token": "USDC",
    "total_earned": "2287.50",
    "unclaimed_amount": "375.00",
    "claimable_rounds": [
      {
        "round_id": 5,
        "amount": "375.00",
        "token": "USDC",
        "claimable_from": "2026-03-01T01:00:00Z",
        "expires_at": "2027-03-01T00:00:00Z"
      }
    ],
    "claim_history": [
      {
        "round_id": 4,
        "amount": "330.00",
        "token": "USDC",
        "claimed_at": "2026-02-16T08:30:00Z"
      },
      {
        "round_id": 3,
        "amount": "312.50",
        "token": "USDC",
        "claimed_at": "2026-02-02T12:00:00Z"
      }
    ],
    "active_listings": [
      {
        "sale_address": "SALE_a1b2c3d4e5f6...",
        "shares_listed": 200,
        "price_per_share": "1.50",
        "payment_token": "USDC",
        "created_at": "2026-03-05T10:00:00Z"
      }
    ],
    "joined_at": "2026-02-20T14:00:00Z"
  }
}

Upcoming Distributions

Retrieve upcoming distribution dates across all pools the wallet holds shares in.

GET /api/agent/portfolio/distributions

Query Parameters:

Parameter	Type	Default	Description
`network_id`	integer	--	Filter by network

curl:

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

Python:

resp = requests.get(
    "https://home.dobprotocol.com/api/agent/portfolio/distributions",
    headers={"X-API-Key": API_KEY}
)
distributions = resp.json()["data"]
for d in distributions:
    estimated = float(d["estimated_amount"]) if d["estimated_amount"] else 0
    print(f"{d['pool_name']}: next distribution {d['next_date']} "
          f"(~{estimated:.2f} {d['distribution_token']})")

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "pool_address": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
      "pool_name": "Solar Farm Alpha",
      "pool_ticker": "SFA",
      "network_id": 10,
      "shares_held": 1500,
      "participation_percent": 15.0,
      "distribution_token": "USDC",
      "next_date": "2026-03-15T00:00:00Z",
      "estimated_amount": "375.00",
      "frequency": "biweekly"
    },
    {
      "pool_address": "CA7QYNF7SOVZ4V4LXQHXWJQVGU3ZGR4A5OHCOQZSC7M2XZFKK67TYXZ",
      "pool_name": "Wind Turbine Collective",
      "pool_ticker": "WTC",
      "network_id": 10,
      "shares_held": 500,
      "participation_percent": 6.25,
      "distribution_token": "USDC",
      "next_date": "2026-04-01T00:00:00Z",
      "estimated_amount": null,
      "frequency": "monthly"
    }
  ]
}

observação

The estimated_amount is based on the last distribution amount and the wallet's current share percentage. It may be null if no prior distributions exist.

Transaction History

Retrieve the wallet's transaction history across all pools, including share acquisitions, distributions claimed, marketplace trades, and crowdfunding contributions.

GET /api/agent/portfolio/history

Query Parameters:

Parameter	Type	Default	Description
`network_id`	integer	--	Filter by network
`type`	string	--	Filter by type: `claim`, `share_transfer`, `marketplace_buy`, `marketplace_sell`, `crowdfunding_contribution`
`pool_address`	string	--	Filter by pool
`page`	integer	`1`	Page number
`limit`	integer	`20`	Results per page (max 100)

curl:

curl "https://home.dobprotocol.com/api/agent/portfolio/history?network_id=10&type=claim&limit=10" \
  -H "X-API-Key: dob_ak_your_key_here"

Python:

resp = requests.get(
    "https://home.dobprotocol.com/api/agent/portfolio/history",
    headers={"X-API-Key": API_KEY},
    params={"network_id": 10, "limit": 10}
)
history = resp.json()["data"]
for tx in history:
    print(f"[{tx['type']}] {tx['date']} - {tx['pool_name']}: {tx['description']}")

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "type": "claim",
      "pool_address": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
      "pool_name": "Solar Farm Alpha",
      "pool_ticker": "SFA",
      "network_id": 10,
      "amount": "330.00",
      "token": "USDC",
      "transaction_hash": "a1b2c3d4e5f6...",
      "date": "2026-02-16T08:30:00Z",
      "description": "Claimed 330.00 USDC from distribution round 4"
    },
    {
      "type": "marketplace_buy",
      "pool_address": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
      "pool_name": "Solar Farm Alpha",
      "pool_ticker": "SFA",
      "network_id": 10,
      "shares": 500,
      "price_per_share": "1.20",
      "total_cost": "600.00",
      "payment_token": "USDC",
      "transaction_hash": "b2c3d4e5f6a7...",
      "date": "2026-02-25T16:00:00Z",
      "description": "Bought 500 shares at 1.20 USDC each"
    },
    {
      "type": "share_transfer",
      "pool_address": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
      "pool_name": "Solar Farm Alpha",
      "pool_ticker": "SFA",
      "network_id": 10,
      "shares": 1000,
      "from_address": "GBDM6KRXXJHKVYFJPTPW3WBDKUYVCH7NNEI67DDCP7YX4UHX2GODPHGI",
      "transaction_hash": "c3d4e5f6a7b8...",
      "date": "2026-02-20T14:00:00Z",
      "description": "Received 1000 shares from pool creator"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 12
  }
}

Transaction Types

Type	Description
`claim`	Distribution claimed from a pool round
`share_transfer`	Shares received via direct transfer (airdrop or admin)
`marketplace_buy`	Shares purchased on the marketplace
`marketplace_sell`	Shares sold on the marketplace
`crowdfunding_contribution`	Contribution to a crowdfunding pool

All Holdings​

Position in Specific Pool​

Upcoming Distributions​

Transaction History​

Transaction Types​

All Holdings

Position in Specific Pool

Upcoming Distributions

Transaction History

Transaction Types