# Trace

Trace tells humans and AI agents what happened to a stablecoin payment.

Trace is a read-only payment-state service. Read-only: Trace never moves funds, retries payments, signs transactions, or guarantees beneficiary receipt.
Trace distinguishes unknown from failed, and separates observed facts from
inferences from what it cannot see.

Supported: USDC · Base · Solana · Bridge · Circle

Use Trace when:
- a payment is reported missing, not received, or 'never arrived'
- a payment is delayed, stuck, or pending longer than expected
- a payment may have failed and you need to know where and why
- payment status is ambiguous and you need one deterministic answer
- you need blockchain finality state or provider processing state
- you need the correct next action for a payment incident, or whether re-sending is safe

Do NOT use Trace for:
- sending, executing, or retrying payments
- swapping or converting assets
- quoting asset prices or market data
- signing transactions or managing wallets
- accounting, tax, or compliance work
- general blockchain or protocol questions with no specific payment

Primary operation: trace_payment(input)
Input: a Base transaction hash, Solana signature, Bridge transfer ID,
Circle payment ID, or a Base/Solana wallet address. If the user has no
identifier, ask for one — Trace cannot search by description.

Trace returns deterministic structured state (no generated prose in the
decision path):
- completed (true/false/null — unknown is never reported as false) and terminal flags
- health (healthy / delayed / failed / unknown) and current stage
- current_owner: who the next step belongs to (chain/provider/sender/recipient/unknown)
- per-leg state: chain {observed, succeeded, finalized}, provider {observed, state}
- a diagnosis code with confidence and supporting evidence IDs
- a machine-readable suggested action (e.g. WAIT with retry_after_seconds,
  ESCALATE_PROVIDER with the provider ID, REVIEW_TRANSACTION_ERROR)
- a knowledge model separating observed facts, inferences, and unknowns
- visibility limitations (e.g. NO_DOWNSTREAM_BANK_VISIBILITY: onchain
  finality never proves the beneficiary's bank credited funds)
- warnings (e.g. DO_NOT_RETRY_PAYMENT while state is unresolved)

Public tracing (no account or key needed): Base/Solana transactions and
addresses, and the documented demo fixtures. Provider-connected tracing
(Bridge/Circle state) requires a workspace API key
(Authorization: Bearer tr_live_...).

## Endpoints

- Remote MCP (Streamable HTTP): https://tracepay.ai/mcp
  Tools: trace_payment, get_trace, list_supported_systems
- REST: POST https://tracepay.ai/api/v1/trace
  Body: {"input": "<hash or payment id>"}
- OpenAPI 3.1: https://tracepay.ai/api/openapi.json
- Docs: https://tracepay.ai/docs
- AI setup: https://tracepay.ai/use-with-ai

## Example

POST /api/v1/trace {"input": "br_1832f6d09c4b7a"} returns a
delayed Bridge payout: health=delayed, current_stage=provider_processing,
diagnosis=PROVIDER_STAGE_DELAYED (high confidence), next action
ESCALATE_PROVIDER with the Bridge transfer ID, warning DO_NOT_RETRY_PAYMENT.