SecondaryDAO API Documentation

Quick Start

Get trading in 3 steps.

1. Create an API Key

Log into SecondaryDAO, go to Profile → API Keys tab. Choose scopes (permissions) and optionally restrict to a specific wallet. Save your secret immediately — it's shown once.

2. Authenticate Requests

Send three headers with every request:
X-SD-KEY — your key ID
X-SD-SECRET — your secret
X-SD-TIMESTAMP — Unix ms (within 30s of server time)

3. Start Trading

Browse properties, check order books, place buy/sell orders, track your portfolio, and claim distribution earnings — all via API.

# Browse properties (public, no auth needed)
curl https://api.secondarydao.com/api/properties

# Check your holdings (auth required)
curl -H "X-SD-KEY: sd_live_a1b2c3d4e5f6" \
     -H "X-SD-SECRET: your96charsecret..." \
     -H "X-SD-TIMESTAMP: $(date +%s000)" \
     https://api.secondarydao.com/api/portfolio/holdings?walletAddress=0xYourWallet
    

Authentication

API key + secret + timestamp on every authenticated request.

Header	Value	Description
`X-SD-KEY`	`sd_live_a1b2c3d4e5f6`	Your API key ID
`X-SD-SECRET`	`<96-char hex>`	Your API secret (never share)
`X-SD-TIMESTAMP`	`1709500000000`	Unix ms, must be within 30s of server time

Scopes

Choose what your key can access when you create it.

Scope	Access
`market:read`	Browse properties, trading status, token stats
`portfolio:read`	View holdings, distributions, performance, income
`orders:read`	View open orders and order history
`orders:write`	Create and cancel buy/sell orders
`trading:execute`	Execute gasless token purchases
`distributions:read`	Unclaimed earnings, claim proofs, claim history
`buyout:read`	View buyout offers, positions, requirements

Wallet Scoping

When creating a key, you can restrict it to a specific wallet or allow access to all wallets on your account. Wallet-scoped keys can only read/write data for that wallet.

Rate Limits

Category	Limit	Window
General API calls	300 requests	1 minute
Order creation	30 requests	1 minute
Trade execution	10 requests	1 minute

Rate limit info returned in RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset headers.

API Endpoints

Complete endpoint reference. Public endpoints need no auth.

Public (No Auth)

Method	Endpoint	Description
GET	`/api/properties`	List all properties with market data
GET	`/api/explorer/properties`	Explorer view with contract addresses
GET	`/api/trading-status/status/:propertyId`	Check if property is trading
GET	`/api/order-book/book/:propertyId`	Order book depth
GET	`/api/merkle/proof/:address`	Merkle proof for on-chain purchases
GET	`/api/token-stats/total-supply`	Total token supply across properties
GET	`/api/buyout/active-offers/:propertyId`	Active buyout offers

Portfolio AUTH

Method	Endpoint	Scope	Description
GET	`/api/portfolio/holdings`	`portfolio:read`	Token holdings for a wallet
GET	`/api/portfolio/summary`	`portfolio:read`	Portfolio summary
GET	`/api/portfolio/distributions`	`portfolio:read`	Distribution payments received
GET	`/api/portfolio/performance`	`portfolio:read`	Performance chart data
GET	`/api/portfolio/trades`	`portfolio:read`	Trade history
GET	`/api/portfolio/income`	`portfolio:read`	Rental income breakdown

Orders & Trading AUTH

Method	Endpoint	Scope	Description
GET	`/api/trading/orders`	`orders:read`	List all orders
GET	`/api/order-book/my-orders`	`orders:read`	Your open orders
POST	`/api/order-book/create`	`orders:write`	Create buy or sell order
POST	`/api/token-purchase/gasless`	`trading:execute`	Gasless token purchase (IPS)

Distributions AUTH

Method	Endpoint	Scope	Description
GET	`/api/distributions/unclaimed/:wallet`	`distributions:read`	Unclaimed earnings
GET	`/api/distributions/claim-data/:wallet`	`distributions:read`	Merkle proofs for claiming
GET	`/api/distributions/history/:wallet`	`distributions:read`	Claim history
POST	`/api/distributions/record-claim`	`distributions:read`	Record on-chain claim

Buyouts AUTH

Method	Endpoint	Scope	Description
GET	`/api/buyout/check-approval/:propertyId`	`buyout:read`	Check if approved for buyout
GET	`/api/buyout/offer-requirements/:propertyId`	`buyout:read`	Requirements for buyout offer
GET	`/api/buyout/my-position/:propertyId`	`buyout:read`	Your token position

View the full guide for request/response examples, field descriptions, and advanced features.

Code Examples

Copy-paste ready examples in Python and JavaScript.

Python

import requests, time

KEY_ID = 'sd_live_a1b2c3d4e5f6'
SECRET = 'your96charsecret...'
BASE   = 'https://api.secondarydao.com'

headers = {
    'X-SD-KEY': KEY_ID,
    'X-SD-SECRET': SECRET,
    'X-SD-TIMESTAMP': str(int(time.time() * 1000))
}

# Get your holdings
r = requests.get(f'{BASE}/api/portfolio/holdings',
    params={'walletAddress': '0xYourWallet'},
    headers=headers)
print(r.json())

# Place a limit buy order
r = requests.post(f'{BASE}/api/order-book/create',
    json={
        'propertyId': '64abc...',
        'orderType': 'buy',
        'executionType': 'limit',
        'tokenAmount': 5,
        'pricePerToken': 1950,
        'walletAddress': '0xYourWallet'
    }, headers=headers)
print(r.json())
    

JavaScript (Node.js)

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://api.secondarydao.com',
  headers: {
    'X-SD-KEY': 'sd_live_a1b2c3d4e5f6',
    'X-SD-SECRET': 'your96charsecret...',
    'X-SD-TIMESTAMP': String(Date.now())
  }
});

// Get holdings
const { data } = await client.get('/api/portfolio/holdings', {
  params: { walletAddress: '0xYourWallet' }
});
console.log(data);

// Place a buy order
const order = await client.post('/api/order-book/create', {
  propertyId: '64abc...',
  orderType: 'buy',
  executionType: 'limit',
  tokenAmount: 5,
  pricePerToken: 1950,
  walletAddress: '0xYourWallet'
});
console.log(order.data);
    