# Trace402 developer guide

> Machine-callable APIs and source-labeled evidence for Algorand.

[OpenAPI](https://trace402.com/openapi.json) · [JSON capabilities](https://trace402.com/api/v1/discovery) · [LLM index](https://trace402.com/llms.txt)

## Current capabilities

### Trace402

Explore Algorand x402 resources, payment activity, transaction verification evidence, wallet trades, and experimental paid APIs. Inspect Algorand transactions with an explicit x402 payment. Saved traces distinguish facilitator claims from independently observed chain evidence and preserve missing or ambiguous evidence.

[Guide](https://trace402.com/index.md)

### Explore services

Discover Algorand x402 services in the facilitator Bazaar catalog. Listings describe offered resources and payment options. A listing is not evidence of payment or a guarantee that a service is currently available.

[Guide](https://trace402.com/explore.md)

### Pulse

Compare partial x402 activity across Algorand, Base, Solana and Polygon, with source attribution and measurement windows. Read-only MainNet comparison preserves Algorand facilitator metrics and Resource Intelligence. External USDC volume supports 7d, 30d and UTC day-to-date (24h selector), with no 1h data or selected-period per-chain settlement counts. Sources have partial coverage; no global total is calculated.

[Guide](https://trace402.com/pulse.md)

### Live settlements

See recent facilitator-reported settlements and successful Labs settlement receipts recorded by Trace402. The bounded live feed merges receipts by network and transaction ID. Receipt evidence does not imply independent chain verification, and summary volumes retain their facilitator source.

[Guide](https://trace402.com/live.md)

### Observed resources

Inspect observed x402 resources, payment activity, freshness, verification context and linked traces. Search, filter and sort the persisted registry. Resource details include 24h or 7d intelligence and observed changes. Unknown payer or verification evidence remains unknown.

[Guide](https://trace402.com/resources.md)

### Smart Wallets

Explore reconstructed Algorand DEX trades, wallet activity and asset flows, including Tinyman V2 swaps. Global activity is bounded and collection may be size-filtered. Wallet access can require a paid one-hour grant. Saved wallet overviews expose observed realized P&L, trade activity, asset exposure and qualification evidence with coverage and freshness. Searches can start or resume existing collection. Standalone performance and qualification routes are currently paused.

[Guide](https://trace402.com/smart-wallets.md)

### Candidate discovery

Explore observed Algorand trading candidates and controlled wallet-analysis selection. Candidate lists, selection progress and saved analysis evidence are available when their stores are configured. These are discovery foundations, not a public Smart Score, Top Traders ranking or an investment recommendation.

[Guide](https://trace402.com/smart-wallets/discovery.md)

### x402 Labs

Experimental machine-callable APIs powered by Trace402, paid per request with Algorand MainNet USDC. Each endpoint is intentionally small. Usage will determine which capabilities become full products. All 6 endpoints cost $0.005 USDC per successful request. Endpoints, prices and response shapes may change.

[Guide](https://trace402.com/labs.md)

### Watchlist

Review your locally saved watchlist and observed changes to x402 resources. Watchlists are stored in your browser. There are no subscriptions or notifications. This personal page is excluded from search indexing.

[Guide](https://trace402.com/watchlist.md)

### Discovery diagnostics

Internal metric distributions and evidence diagnostics for analyzed discovery candidates. Observational diagnostics include availability and freshness. They are not a product score or automated strategy recommendation. This diagnostics page is excluded from search indexing.

[Guide](https://trace402.com/smart-wallets/discovery/analytics.md)

## x402 payment and access

Runtime network: Algorand MainNet. Read GET /api/v1/config for current inspection configuration. Labs are Experimental and require MainNet USDC ASA 31566704: $0.005 USDC (5000 atomic units) per successful request. Wallet unlock prices come from the offered challenge.

1. GET the exact resource URL without a signature. A valid unpaid paid-resource request returns 402 and, where available, PAYMENT-REQUIRED (base64 x402 v2 JSON). A wallet-grant 402 is an access error: obtain the challenge from the wallet unlock route.
2. Check offered network, asset, atomic amount, recipient and resource. Obtain explicit spending authorization before signing. Retry the same URL with PAYMENT-SIGNATURE only after approving that offer.
3. Read the response and PAYMENT-RESPONSE receipt. Submitted or verified payment is not confirmed settlement. Preserve transaction ID and source evidence. Do not automatically retry after an uncertain settlement or a settled-but-failed response.
4. Wallet unlock issues an HttpOnly same-site cookie scoped to the requested wallet for one hour. Preserve cookies for later wallet reads; it is not an API key or a subscription.

Unpaid example (does not sign or spend):

```sh
curl -i 'https://trace402.com/api/v1/labs/blocks/details?round=65699106'
```

## Evidence, errors and responsible reads

Coverage can be empty, partial, stale or unknown. A Bazaar listing is not a settlement. Facilitator activity metrics exclude local Labs receipt totals; Live merges those receipts separately. Saved verification checks captured evidence and preserves ambiguous candidates. Block details use one header-only Indexer lookup and string integers; the ledger transaction counter is not this block's transaction count. Wallet summaries use persisted trades without new indexing. Global wallet collection may be size-filtered; full-history and profitability claims require the response's coverage evidence.

JSON APIs return source-specific shapes. Labs responses include schemaVersion, status=Experimental, network=mainnet, asOf, scope and data. asOf is response generation time except resource usage's source snapshot; inspect source timestamps for freshness. Preserve decimal/atomic strings instead of rounding through floating point.

400 means invalid input, 402 payment/access required, 404 missing evidence, 429 rate limit (honor Retry-After), and 5xx unavailable upstream/storage/payment. Smart Wallet performance and qualification routes currently return 409 (paused). Do not treat an error or empty response as zero activity. Poll sparingly, honor HTTP cache headers and source freshness, and avoid wallet refresh/analysis mutations during crawling. The reference documents reads and bounded watchlist snapshots; operational analysis, selection and recalculation writes are intentionally outside autonomous discovery.

## API reference

### Runtime configuration

`GET /api/v1/config`

Access: public. Current network, inspection price, public origin and wallet-payment enablement. No credentials.

### Network metrics

`GET /api/v1/network/metrics`

Access: public. ALGO market price and facilitator settlement count, with source and freshness.

### Combined Pulse

`GET /api/v1/pulse`

Access: public. Source-labeled activity and persisted Resource Intelligence. Observed intelligence supports 24h/7d; coverage is incomplete.

Parameters:

- `period` (query):  Schema: `{"type":"string","enum":["1h","24h","7d","30d"],"default":"24h"}`
- `network` (query):  Schema: `{"type":"string","enum":["mainnet","testnet","all"],"default":"mainnet"}`

### Multi-chain Pulse

`GET /api/v1/pulse/networks`

Access: public. Read-only Algorand, Base, Solana and Polygon comparison. Partial attributed coverage, no global totals. External 24h is UTC day-to-date; 1h and per-chain period counts are unavailable.

Parameters:

- `period` (query):  Schema: `{"type":"string","enum":["1h","24h","7d","30d"],"default":"7d"}`

### Bazaar catalog

`GET /api/v1/x402/resources`

Access: public. Facilitator resource declarations; listings do not prove payment or current availability. Pagination uses source pages and can be sparse.

Parameters:

- `network` (query):  Schema: `{"type":"string","enum":["mainnet","testnet","all"],"default":"mainnet"}`
- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":100,"default":24}`
- `offset` (query):  Schema: `{"type":"integer","minimum":0,"default":0}`

### Settlement activity summary

`GET /api/v1/x402/activity/summary`

Access: public. Facilitator-reported settlement metrics. Local Labs receipts do not increase these totals.

Parameters:

- `period` (query):  Schema: `{"type":"string","enum":["1h","24h","7d","30d"],"default":"24h"}`
- `network` (query):  Schema: `{"type":"string","enum":["mainnet","testnet","all"],"default":"mainnet"}`

### Settlement activity recent

`GET /api/v1/x402/activity/recent`

Access: public. Facilitator settlements merged with confirmed local Labs receipts, deduplicated by network and transaction ID. Incomplete coverage; not independent verification.

Parameters:

- `period` (query):  Schema: `{"type":"string","enum":["1h","24h","7d","30d"],"default":"24h"}`
- `network` (query):  Schema: `{"type":"string","enum":["mainnet","testnet","all"],"default":"mainnet"}`
- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":100,"default":50}`
- `cursor` (query): Timestamp cursor returned by the feed; not an offset. Schema: `{"type":"string","pattern":"^\\d+$"}`

### Settlement activity series

`GET /api/v1/x402/activity/series`

Access: public. Facilitator-reported settlement metrics. Local Labs receipts do not increase these totals.

Parameters:

- `period` (query):  Schema: `{"type":"string","enum":["1h","24h","7d","30d"],"default":"24h"}`
- `network` (query):  Schema: `{"type":"string","enum":["mainnet","testnet","all"],"default":"mainnet"}`

### Observed resource registry

`GET /api/v1/resources`

Access: public. Persisted observations, not the Bazaar listing catalog. This read can refresh observations from the existing activity feed.

Parameters:

- `search` (query):  Schema: `{"type":"string","maxLength":120}`
- `status` (query):  Schema: `{"type":"string","enum":["active","stale","unknown"]}`
- `sort` (query):  Schema: `{"type":"string","enum":["activity","new","price"],"default":"activity"}`
- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":100,"default":24}`
- `offset` (query):  Schema: `{"type":"integer","minimum":0,"default":0}`

### Resource details

`GET /api/v1/resources/{resourceId}`

Access: public. Observed resource metadata and evidence.

Parameters:

- `resourceId` (path, required): Observed registry ID. Schema: `{"type":"string","pattern":"^[0-9a-f]{64}$"}`

### Resource activity

`GET /api/v1/resources/{resourceId}/activity`

Access: public. Persisted observations with explicit freshness and incomplete coverage.

Parameters:

- `resourceId` (path, required): Observed registry ID. Schema: `{"type":"string","pattern":"^[0-9a-f]{64}$"}`
- `period` (query):  Schema: `{"type":"string","enum":["24h","7d"],"default":"24h"}`

### Resource intelligence

`GET /api/v1/resources/{resourceId}/intelligence`

Access: public. Persisted observations with explicit freshness and incomplete coverage.

Parameters:

- `resourceId` (path, required): Observed registry ID. Schema: `{"type":"string","pattern":"^[0-9a-f]{64}$"}`
- `period` (query):  Schema: `{"type":"string","enum":["24h","7d"],"default":"24h"}`

### Watchlist snapshot

`POST /api/v1/resources/watchlist`

Access: public. Read a bounded set of resources and observed changes. Does not create a server subscription.

JSON body schema: `{"type":"object","additionalProperties":false,"properties":{"resourceIds":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"since":{"type":"string","format":"date-time","description":"Canonical ISO UTC timestamp, not in the future."}},"required":["resourceIds"]}`

### Watchlist intelligence

`POST /api/v1/resources/watchlist/intelligence`

Access: public. Read persisted intelligence for a bounded resource list; no notifications.

JSON body schema: `{"type":"object","additionalProperties":false,"properties":{"resourceIds":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"period":{"type":"string","enum":["24h","7d"],"default":"24h"}},"required":["resourceIds"]}`

### Saved public trace

`GET /api/v1/traces/{traceId}`

Access: public. Public evidence projection; signatures and session secrets are excluded. A legacy trace can be enriched from existing chain evidence. Missing evidence remains unknown.

Parameters:

- `traceId` (path, required):  Schema: `{"type":"string","format":"uuid"}`

### Paid transaction inspection

`GET /api/v1/inspect/algorand/transactions/{txId}`

Access: x402. Normalized transaction participants, transfers, fees, block and application-call context. Read runtime config and the exact x402 challenge; prices are not hardcoded here.

Parameters:

- `txId` (path, required):  Schema: `{"type":"string","pattern":"^[A-Z2-7]{52}$"}`

### Unlock wallet access

`GET /api/v1/smart-wallets/{address}/unlock`

Access: x402. When enabled, x402 settlement grants one hour of access to the requested wallet using an HttpOnly same-site cookie. Preserve that cookie for subsequent wallet reads. Read the exact challenge for the price.

Parameters:

- `address` (path, required): Checksummed Algorand address. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`

### Global trade overview

`GET /api/v1/smart-wallets/overview`

Access: public. Persisted, possibly size-filtered collection with explicit coverage.

### Trade history

`GET /api/v1/smart-wallets/trades`

Access: public. Reconstructed DEX trades; wallet-filtered queries require a paid grant when enabled.

Parameters:

- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":100,"default":25}`
- `page` (query):  Schema: `{"type":"integer","minimum":1,"maximum":10000,"default":1}`
- `wallet` (query): Wallet-filtered queries require a wallet grant when payments are enabled. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`
- `asset` (query): uint64 asset ID. Schema: `{"type":"string","pattern":"^\\d{1,20}$"}`
- `dex` (query):  Schema: `{"type":"string","minLength":1,"maxLength":64}`
- `from` (query):  Schema: `{"type":"string","format":"date-time"}`
- `to` (query):  Schema: `{"type":"string","format":"date-time"}`
- `assetScope` (query):  Schema: `{"type":"string","enum":["core","all","pair","algo-usdc"]}`
- `mode` (query):  Schema: `{"type":"string","enum":["recent","history"]}`
- `refresh` (query):  Schema: `{"type":"string","enum":["background","wait","read","continue"]}`

### Wallet activity

`GET /api/v1/smart-wallets/{address}`

Access: wallet-grant. Wallet summary, latest 20 activity items and separate paginated history. Use refresh=read for existing cache; this route can otherwise start or resume existing wallet collection.

Side effects: Can start/resume existing wallet collection unless refresh=read.

Parameters:

- `address` (path, required): Checksummed Algorand address. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`
- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":100,"default":25}`
- `page` (query):  Schema: `{"type":"integer","minimum":1,"maximum":10000,"default":1}`
- `wallet` (query): Wallet-filtered queries require a wallet grant when payments are enabled. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`
- `asset` (query): uint64 asset ID. Schema: `{"type":"string","pattern":"^\\d{1,20}$"}`
- `dex` (query):  Schema: `{"type":"string","minLength":1,"maxLength":64}`
- `from` (query):  Schema: `{"type":"string","format":"date-time"}`
- `to` (query):  Schema: `{"type":"string","format":"date-time"}`
- `assetScope` (query):  Schema: `{"type":"string","enum":["core","all","pair","algo-usdc"]}`
- `mode` (query):  Schema: `{"type":"string","enum":["recent","history"]}`
- `refresh` (query):  Schema: `{"type":"string","enum":["background","wait","read","continue"]}`

### Wallet trade history

`GET /api/v1/smart-wallets/{address}/trades`

Access: wallet-grant. Persisted paginated trades with filters and coverage.

Parameters:

- `address` (path, required): Checksummed Algorand address. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`
- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":100,"default":25}`
- `page` (query):  Schema: `{"type":"integer","minimum":1,"maximum":10000,"default":1}`
- `wallet` (query): Wallet-filtered queries require a wallet grant when payments are enabled. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`
- `asset` (query): uint64 asset ID. Schema: `{"type":"string","pattern":"^\\d{1,20}$"}`
- `dex` (query):  Schema: `{"type":"string","minLength":1,"maxLength":64}`
- `from` (query):  Schema: `{"type":"string","format":"date-time"}`
- `to` (query):  Schema: `{"type":"string","format":"date-time"}`
- `assetScope` (query):  Schema: `{"type":"string","enum":["core","all","pair","algo-usdc"]}`
- `mode` (query):  Schema: `{"type":"string","enum":["recent","history"]}`
- `refresh` (query):  Schema: `{"type":"string","enum":["background","wait","read","continue"]}`

### Wallet overview

`GET /api/v1/smart-wallets/{address}/overview`

Access: wallet-grant. Existing saved analysis or analysis progress; requires configured analysis store. No completeness guarantee.

Parameters:

- `address` (path, required): Checksummed Algorand address. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`

### Wallet assets

`GET /api/v1/smart-wallets/{address}/assets`

Access: wallet-grant. Existing saved analysis or analysis progress; requires configured analysis store. No completeness guarantee.

Parameters:

- `address` (path, required): Checksummed Algorand address. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`

### Wallet analysis-status

`GET /api/v1/smart-wallets/{address}/analysis-status`

Access: wallet-grant. Existing saved analysis or analysis progress; requires configured analysis store. No completeness guarantee.

Parameters:

- `address` (path, required): Checksummed Algorand address. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`

### Observed candidates

`GET /api/v1/smart-wallets/candidates`

Access: public. Activity-based discovery foundations, not a Smart Score or investment ranking.

Parameters:

- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":100,"default":25}`
- `offset` (query):  Schema: `{"type":"integer","minimum":0,"maximum":100000,"default":0}`
- `sort` (query):  Schema: `{"type":"string","enum":["tradeCount","valuedVolumeUsd","activeDays","assetsTraded","lastActivity"],"default":"tradeCount"}`
- `minTrades` (query):  Schema: `{"type":"integer","minimum":0,"maximum":2147483647,"default":0}`
- `minActiveDays` (query):  Schema: `{"type":"integer","minimum":0,"maximum":365,"default":0}`
- `minValuedVolumeUsd` (query): Non-negative exact decimal string; default 0. Schema: `{"type":"string"}`
- `priority` (query):  Schema: `{"type":"string","enum":["eligible","observed"]}`
- `analysisStatus` (query):  Schema: `{"type":"string","enum":["not-analyzed","analyzed","analyzing"]}`

### Candidate progress

`GET /api/v1/smart-wallets/candidates/progress`

Access: public. Current collector/selection state when configured. Observational, no new selection is triggered.

### Candidate selection-stats

`GET /api/v1/smart-wallets/candidates/selection-stats`

Access: public. Current collector/selection state when configured. Observational, no new selection is triggered.

### Discovery diagnostics

`GET /api/v1/smart-wallets/discovery/analytics`

Access: public. Internal observational distributions, coverage and freshness. Not a product score.

Parameters:

- `population` (query):  Schema: `{"type":"string","enum":["qualified","unqualified","all"],"default":"qualified"}`
- `sort` (query):  Schema: `{"type":"string","enum":["realizedPnlUsd","demonstratedReturnPct","profitFactor","winRate","expectancyPct","payoffRatio","valuedVolumeUsd30d","tradeCount30d","activeDays30d","assetsTraded30d","economicPnlCoverage","valuationCoverage","contributingCoverage","profitablePeriodRatio","topAssetConcentrationPct"],"default":"demonstratedReturnPct"}`
- `direction` (query):  Schema: `{"type":"string","enum":["asc","desc"],"default":"desc"}`
- `freshness` (query):  Schema: `{"type":"string","enum":["current","stale","all"],"default":"current"}`
- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":100,"default":25}`
- `offset` (query):  Schema: `{"type":"integer","minimum":0,"maximum":100000,"default":0}`

### Recent settlements

`GET /api/v1/labs/settlements/recent`

Access: x402 · Experimental. Recent successful Algorand MainNet USDC x402 settlements reported by the facilitator. limit: 1–20 (default 10). Fixed 24h window; coverage is incomplete. $0.005 USDC per successful request. Coverage may be partial.

Parameters:

- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":20,"default":10}`

### Active x402 resources

`GET /api/v1/labs/resources/active`

Access: x402 · Experimental. Active MainNet resources in the existing observed resource registry. limit: 1–20 (default 10). Active means recently observed, not guaranteed availability. $0.005 USDC per successful request. Coverage may be partial.

Parameters:

- `limit` (query):  Schema: `{"type":"integer","minimum":1,"maximum":20,"default":10}`

### Resource usage summary

`GET /api/v1/labs/resources/usage`

Access: x402 · Experimental. Observed payments, freshness and evidence coverage for one resource. resourceId: 64-character registry ID; period: 24h or 7d (default 24h). $0.005 USDC per successful request. Coverage may be partial.

Parameters:

- `resourceId` (query, required): Observed registry ID. Schema: `{"type":"string","pattern":"^[0-9a-f]{64}$"}`
- `period` (query):  Schema: `{"type":"string","enum":["24h","7d"],"default":"24h"}`

### Verify settlement

`GET /api/v1/labs/settlements/verify`

Access: x402 · Experimental. Verification checks and provenance from an existing saved MainNet payment trace. traceId: saved trace UUID. Reuses captured evidence; does not claim fresh chain verification. $0.005 USDC per successful request. Coverage may be partial.

Parameters:

- `traceId` (query, required): Existing saved MainNet trace; no fresh verification. Schema: `{"type":"string","format":"uuid"}`

### Wallet intelligence summary

`GET /api/v1/labs/wallets/summary`

Access: x402 · Experimental. A small summary of persisted MainNet DEX trades for one wallet. address: checksummed Algorand address. Persisted trades only; no backfill, scoring or complete-history claim. $0.005 USDC per successful request. Coverage may be partial.

Parameters:

- `address` (query, required): Checksummed address; persisted trades only, no backfill. Schema: `{"type":"string","pattern":"^[A-Z2-7]{58}$"}`

### Block / round details

`GET /api/v1/labs/blocks/details`

Access: x402 · Experimental. Compact Algorand MainNet block metadata for one round from the configured Indexer. round: decimal block / round ID (0–18446744073709551615). Header metadata only; transactions are excluded. Integer fields are returned as strings. $0.005 USDC per successful request. Coverage may be partial.

Parameters:

- `round` (query, required): Canonical uint64 decimal, at most 18446744073709551615. Header only; integers are strings. Schema: `{"type":"string","pattern":"^(0|[1-9]\\d{0,19})$"}`

### Experimental Labs catalog

`GET /api/v1/labs/catalog`

Access: public. Free discovery of all Labs endpoints, prices, query guidance and current payment enablement.