API Reference
Public read-only API for indexed agent data and the matching TypeScript SDK for writes plus
explorer reads. Base URL: https://stellar8004.com
Endpoints
OpenAPI spec| Method | Path | Description |
|---|---|---|
| GET | /api/v1/agents | List all agents with pagination and filtering |
| GET | /api/v1/agents/:id | Get agent details including metadata and scores |
| GET | /api/v1/agents/:id/feedback | List feedback for a specific agent |
| GET | /api/v1/accounts/:address/agents | List agents owned by a wallet address |
| GET | /api/v1/search?q=... | Full-text search across agents |
| GET | /api/v1/stats | Aggregate network statistics |
| GET | /api/v1/health | Indexer health status |
| GET | /api/v2/discovery?network=mainnet | Cursor-paged discovery: strict filters, stable score/newest/id order, 0-100 score |
/api/v1/agentsList all agents with pagination and filtering
/api/v1/agents/:idGet agent details including metadata and scores
/api/v1/agents/:id/feedbackList feedback for a specific agent
/api/v1/accounts/:address/agentsList agents owned by a wallet address
/api/v1/search?q=...Full-text search across agents
/api/v1/statsAggregate network statistics
/api/v1/healthIndexer health status
/api/v2/discovery?network=mainnetCursor-paged discovery: strict filters, stable score/newest/id order, 0-100 score
Quick Start
SDK Quick Start
The SDK gives you one surface for testnet funding, metadata building, automatic storage selection, Soroban contract writes, and read-only explorer queries. The fastest onboarding path is: fund -> signer -> client -> metadata -> storage -> register.
Install
ERC-8004 spec
Canonical protocol definition, metadata type URI, and registry model.
Contract source
Identity, reputation, and validation registry source for Stellar.
Testnet faucet
Fund a fresh Stellar keypair with testnet XLM before registering.
Best practices
Practical metadata parsing and validation guidance for ERC-8004.
Metadata size helper
Use the live register flow to watch metadata byte size before uploading.
Prerequisites
Stellar keypairs
Use Keypair.random() for a disposable testnet identity or Keypair.fromSecret(secret) to automate an existing wallet.
Funding
On testnet you can use fundTestnet() or the Stellar Lab faucet. On mainnet you must provide your own XLM and override TESTNET_CONFIG.
Pinata JWT
Optional. AutoStorage only needs PINATA_JWT when metadata grows past the 8KB data URI limit.
Five-step flow
- 1
Install the SDK and tsx for one-file scripts.
- 2
Create or load a Stellar keypair and fund it on testnet.
- 3
Build metadata with buildMetadataJson() and inspect its byte size.
- 4
Upload through AutoStorage so small payloads stay as data URIs.
- 5
Register on Soroban, then verify through the Explorer API.
Minimal register example
Registration Flow
The diagram below shows the happy path from local script or browser app to on-chain registration and indexed discovery.
Example Register Script
Save as register.ts and run npx tsx register.ts.
API Client Examples
Browser and CORS notes
- ExplorerClient wraps the same public GET endpoints documented above, so it works
anywhere
fetchis available. - For browser apps, point it at
https://stellar8004.comfor direct public reads. - If your own mirror or proxy tightens cross-origin rules, call the explorer from your backend instead and keep the client code unchanged.
- Writes use the contract binding clients (e.g.
IdentityClient), which sign locally and submit directly to Soroban RPC.
Response Format
Rate Limits
30 req/min IP-based, best-effortError Responses
| Code | HTTP | Description |
|---|---|---|
| INVALID_PARAM | 400 | Invalid or unknown query parameter |
| MISSING_PARAM | 400 | Required parameter missing |
| INVALID_ID | 400 | Agent ID is not a number |
| INVALID_ADDRESS | 400 | Not a Stellar account address |
| INVALID_CURSOR | 400 | Cursor is malformed or from another query |
| NOT_FOUND | 404 | Agent or endpoint not found |
| METHOD_NOT_ALLOWED | 405 | Only GET is supported |
| RATE_LIMITED | 429 | Over 30 requests per minute |
| INTERNAL_ERROR | 500 | Server error, retry with backoff |
| INDEX_STALE | 503 | Discovery only: the index is behind the chain |
INVALID_PARAMInvalid or unknown query parameter
MISSING_PARAMRequired parameter missing
INVALID_IDAgent ID is not a number
INVALID_ADDRESSNot a Stellar account address
INVALID_CURSORCursor is malformed or from another query
NOT_FOUNDAgent or endpoint not found
METHOD_NOT_ALLOWEDOnly GET is supported
RATE_LIMITEDOver 30 requests per minute
INTERNAL_ERRORServer error, retry with backoff
INDEX_STALEDiscovery only: the index is behind the chain