REST API reference. Public marketplace endpoints, internal agent routes, gossip protocol, and node discovery via .well-known/agent.
Every node serves a full REST API independently. The API is split into two tiers: the public marketplace API (read-only, open access) and the internal agent API (node-authenticated, protocol operations).
Base URL: /api/market/v1/{chain} where {chain} is BTC, ETH, or SOL.
GET /api/market/v1/{chain}/collections
GET /api/market/v1/{chain}/collections/{id}
GET /api/market/v1/{chain}/collections/{id}/statsBrowse collections with metadata, floor prices, and volume stats. Stats include 24h/7d/30d volume, floor price history, and unique holder count.
GET /api/market/v1/{chain}/asks
GET /api/market/v1/{chain}/asks?status=OPEN
GET /api/market/v1/{chain}/asks?collection={id}
GET /api/market/v1/{chain}/asks?seller={address}
GET /api/market/v1/{chain}/asks?minPrice={sats|wei|lamports}
GET /api/market/v1/{chain}/asks?maxPrice={sats|wei|lamports}Status-filtered listing queries with collection, seller, and price range filtering.
GET /api/market/v1/{chain}/bids
GET /api/market/v1/{chain}/bids?buyer={address}
GET /api/market/v1/{chain}/bids?listing={outpoint}Buyer and listing-scoped offer queries.
GET /api/market/v1/{chain}/activity
GET /api/market/v1/{chain}/activity?kind=SALE
GET /api/market/v1/{chain}/activity?collection={id}
GET /api/market/v1/{chain}/activity?address={address}Transaction history filtered by event kind (SALE, LIST, DELIST, TRANSFER).
GET /api/market/v1/{chain}/tokens
GET /api/market/v1/{chain}/tokens/{id}
GET /api/market/v1/{chain}/tokens/{id}/history
GET /api/market/v1/{chain}/tokens/{id}/holdersFungible token boards, price history, and holder distribution.
GET /api/market/v1/{chain}/wallets/{address}/listings
GET /api/market/v1/{chain}/wallets/{address}/activity
GET /api/market/v1/{chain}/wallets/{address}/balancesPer-wallet marketplace data: active listings, trade history, token balances.
These routes handle node-to-node protocol operations. All require node authentication (Ed25519 signed request headers).
POST /api/agent/btc/list # Submit BTC listing
POST /api/agent/btc/delist # Cancel BTC listing
POST /api/agent/btc/purchase # Submit BTC purchase intent
POST /api/agent/btc/validate # Validate BTC transactionPOST /api/agent/evm/list # Submit EVM listing
POST /api/agent/evm/delist # Cancel EVM listing
POST /api/agent/evm/purchase # Submit EVM purchase intent
POST /api/agent/evm/validate # Validate EVM transactionPOST /api/agent/sol/list # Submit SOL listing
POST /api/agent/sol/delist # Cancel SOL listing
POST /api/agent/sol/purchase # Submit SOL purchase intent
POST /api/agent/sol/validate # Validate SOL transactionPOST /api/agent/psbt-share/distribute # Distribute PSBT shards to cohort
POST /api/agent/psbt-share/store # Store a shard on this node
POST /api/agent/psbt-share/challenge # Request reveal challenge
POST /api/agent/psbt-share/reveal # Retrieve shard with valid challenge
POST /api/agent/psbt-share/coverage # Query shard coverage status
POST /api/agent/psbt-share/rebalance # Trigger shard rebalancingPOST /api/gossip/push # Push protocol events to peer
POST /api/gossip/pull # Pull events from peer
POST /api/gossip/heartbeat # Heartbeat exchange
POST /api/gossip/membership # Membership change notification
POST /api/gossip/sync # Full state sync requestPOST /api/protocol/events # Submit signed protocol event
GET /api/protocol/events/{id} # Query event by ID
GET /api/protocol/state # Current protocol state snapshot
POST /api/protocol/validate # Validate event without submittingPOST /api/admin/governance/propose # Submit governance proposal
POST /api/admin/governance/vote # Vote on proposal
POST /api/admin/strikes/issue # Issue misbehavior strike
GET /api/admin/health # Node health status
GET /api/admin/metrics # Prometheus-compatible metricsGET /api/media/{hash} # Retrieve cached media by content hash
POST /api/media/upload # Upload media (rate limited)
GET /api/media/status/{hash} # Check media availability across shardsGET /.well-known/agent
GET /.well-known/agent/fee-addresses?chain=BTC&context=<key>/.well-known/agent returns the node's public identity plus its advertised capabilities.
Fee address catalogs are fetched separately from /.well-known/agent/fee-addresses so discovery stays small.
{
"nodeId": "node-abc123",
"agentPubkey": "ed25519:...",
"foundationFeeAddress": "bc1qfoundation...",
"capabilities": ["protocol_validate", "ui_quote_service"],
"protocolVersion": "mvp-1",
"validatorVersion": "1.0.0"
}Other nodes use this endpoint during peer discovery and mesh formation.
All public endpoints return paginated responses:
{
"data": [...],
"pagination": {
"offset": 0,
"limit": 20,
"total": 150
}
}| Tier | Limit | Escalation |
|---|---|---|
| Anonymous | 60 req/min | Standard |
| Authenticated | 300 req/min | Standard |
| Abusive (tier 1) | Blocked 5 min | After repeated violations |
| Abusive (tier 2) | Blocked 15 min | Continued abuse |
| Abusive (tier 3) | Blocked 60 min | Persistent abuse |
| Abusive (tier 4) | Blocked 24h + gossip ban | Ban propagated to all nodes |
Rate limit violations trigger escalating cooldowns. At tier 4, the ban is gossiped to all nodes in the network, effectively blocking the client from the entire mesh.