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
| 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 |
/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
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_PARAMS | 400 | Missing or invalid query parameters |
| NOT_FOUND | 404 | Agent or endpoint not found |
| RATE_LIMITED | 429 | Too many requests - try again later |
| INTERNAL_ERROR | 500 | Server error - retry with backoff |
INVALID_PARAMSMissing or invalid query parameters
NOT_FOUNDAgent or endpoint not found
RATE_LIMITEDToo many requests - try again later
INTERNAL_ERRORServer error - retry with backoff