One API for understanding what happened to a stablecoin payment.

Trace normalizes blockchain and provider state into one deterministic payment trace. Instead of separately understanding Base receipts, Solana commitments, Bridge transfer states, and Circle payment statuses, you call one endpoint and get one normalized answer: what happened, where the money is, and what should happen next — with the evidence behind every claim.

Read-only. Trace never moves funds, signs transactions, or guarantees beneficiary receipt. Supported systems: USDC · Base · Solana · Bridge · Circle.

Quick start

Trace a payment. Onchain transactions and the demo fixtures work without authentication:

curl -s https://tracepay.ai/api/v1/trace \
  -H "Content-Type: application/json" \
  -d '{"input": "br_1832f6d09c4b7a"}'

The response is a single normalized trace:

{
  "schema_version": "1.0",
  "request_id": "req_...",
  "result": "trace",
  "trace": {
    "trace_id": "tr_...",
    "visibility": "full",
    "payment": { "asset": "USDC", "amount": "12400.00",
                 "chain": "base", "provider": "bridge", ... },
    "state": { "normalized_status": "provider_processing",
               "health": "delayed",
               "current_stage": "provider_processing",
               "terminal": false },
    "timing": { "elapsed_seconds": 2340, "delay_seconds": 1320, ... },
    "diagnosis": {
      "code": "PROVIDER_STAGE_DELAYED",
      "confidence": "high",
      "summary": "Onchain settlement completed, but the payment
                  remains pending at the provider stage.",
      "suggested_action": { "code": "ESCALATE_PROVIDER",
                            "provider": "bridge",
                            "external_id": "br_..." },
      "evidence_ids": ["ev_..."]
    },
    "stages": [...], "evidence": [...],
    "limitations": [{ "code": "NO_DOWNSTREAM_BANK_VISIBILITY", ... }]
  }
}

Demo inputs that always work: br_1832f6d09c4b7a (delayed payout), 0x32e1e7401c54f35aff... (successful Base transfer), 3YY5vfJsRYqYuEQLKxke... (failed Solana transfer). The full OpenAPI 3.1 spec is at /api/openapi.json.

Authentication

Anonymous requests can trace public onchain transactions and the demo fixtures, rate-limited by client. Tracing payments through your connected Bridge/Circle credentials and listing saved traces require a workspace API key:

Authorization: Bearer tr_live_...

Create keys under Settings → API keys. The secret is shown exactly once at creation; Trace stores only a hash. Revoked keys stop working immediately. Scope is trace:read — keys can only read payment state. In local demo mode the documented key tr_demo_readonly is also accepted.

Endpoints

POST /api/v1/trace	Trace a payment from any supported identifier. The primary endpoint.
GET /api/v1/traces/:id	Retrieve an existing trace.
GET /api/v1/traces	List workspace traces (authenticated). Filters: status, health, chain, provider, limit.
GET /api/v1/public/traces/:shareId	Retrieve an explicitly shared trace.
GET /api/openapi.json	OpenAPI 3.1 specification.

Address inputs with multiple recent USDC transfers return result: "selection_required" with the candidate transactions rather than silently picking one. Every response carries schema_version, a request_id (also in the X-Trace-Request-Id header), and partial evidence is returned as a trace with limitations, never as an error.

Status semantics

These distinctions are fundamental. Build logic on them.

completed	Explicit provider evidence that the flow reached its terminal completed state.
onchain_finalized	Blockchain execution finalized successfully. Does NOT mean the beneficiary received fiat.
provider_processing	The provider accepted the payment but has not reported terminal completion.
failed	Explicit evidence of failure, onchain or at the provider.
unknown	Evidence is insufficient. Trace never guesses.

state.terminal is true only for completed and failed. visibility says which legs Trace could observe: full · partial · chain_only · provider_only · unknown.

Diagnosis and action codes

Agents should branch on codes, never on prose. diagnosis.code is one of:

PAYMENT_COMPLETEDONCHAIN_PENDINGONCHAIN_DELAYEDONCHAIN_FAILEDONCHAIN_SETTLEDFUNDS_RECEIVED_NO_ONCHAINPROVIDER_AWAITING_FUNDSPROVIDER_PROCESSINGPROVIDER_STAGE_DELAYEDPROVIDER_FAILEDPARTIAL_VISIBILITYUNKNOWN_STATE

diagnosis.suggested_action.code is one of:

NONEWAITRETRY_LOOKUPCHECK_PROVIDERESCALATE_PROVIDERCHECK_CHAINREVIEW_TRANSACTION_ERRORREQUEST_MORE_INFORMATION

Actions are recommendations only — Trace never executes them. WAIT actions include retry_after_seconds. Every diagnosis lists the evidence_ids that support it.

Limitations model

Trace states what it cannot see, so partial evidence is never mistaken for absolute truth. limitations[].code is one of:

NO_PROVIDER_CONNECTIONNO_DOWNSTREAM_BANK_VISIBILITYPROVIDER_UNAVAILABLECHAIN_RPC_UNAVAILABLECORRELATION_INFERRED

The most important one: NO_DOWNSTREAM_BANK_VISIBILITY. Onchain finality plus provider submission does not prove the beneficiary's bank credited the funds. Trace will never claim beyond its evidence.

Error codes

INVALID_REQUEST	Malformed body or parameters. Not retryable.
UNSUPPORTED_INPUT	Input is not a supported transaction, ID, or address.
INPUT_NOT_FOUND	No chain transaction or provider payment matched the input.
PROVIDER_NOT_CONNECTED	Input looks like a provider ID but no provider credentials are configured.
SOURCE_UNAVAILABLE	An upstream RPC or provider API is down. Retryable.
RATE_LIMITED	Too many requests. Retry after retry_after_seconds.
UNAUTHORIZED	Missing, unknown, malformed, or revoked API key.
FORBIDDEN	Authenticated but not allowed to access this resource.
NOT_FOUND	The requested trace does not exist or is not visible to you.
INTERNAL_ERROR	Unexpected server error. Retryable.

Errors are always {"error": {"code", "message", "retryable"}} with appropriate HTTP status codes. Rate limits (default 60 requests per 60 seconds, configurable) return 429 with retry_after_seconds.

MCP

Trace is an MCP server. Remote (Streamable HTTP) — point any MCP-compatible client at:

https://tracepay.ai/mcp

Three read-only tools: trace_payment, get_trace, list_supported_systems. Public blockchain tracing needs no authentication; add a workspace API key as a bearer token for provider-connected tracing. A local stdio server is also available for clients that spawn processes:

{
  "mcpServers": {
    "trace": {
      "command": "node",
      "args": ["mcp/server.mjs"],
      "env": {
        "TRACE_API_URL": "https://tracepay.ai",
        "TRACE_API_KEY": "tr_live_..."
      }
    }
  }
}

From the repository: npm run mcp. TRACE_API_KEY is optional for public/demo tracing. Setup for specific clients: /use-with-ai. Worked agent example: /docs/agents. Machine summary: /llms.txt.

Supported systems

Asset: USDC. Chains: base, solana. Providers: bridge, circle. Trace is deliberately narrow: it does one thing — explain what happened to a stablecoin payment — with evidence for every claim.