{"openapi":"3.1.0","info":{"title":"Trace API","version":"1.0","description":"One deterministic interface for understanding what happened to a stablecoin payment. Trace normalizes blockchain (Base, Solana) and provider (Bridge, Circle) state for USDC payments into a single canonical trace with evidence-backed diagnosis. Read-only: Trace never moves funds, signs transactions, or guarantees beneficiary receipt."},"servers":[{"url":"https://tracepay.ai"}],"security":[{"bearerAuth":[]},{}],"paths":{"/api/v1/trace":{"post":{"operationId":"tracePayment","summary":"Trace a payment","description":"Use this whenever you need to determine whether a supported USDC payment completed, failed, or is delayed — where it currently is, who owns the next step, and what should happen next. Accepts a Base transaction hash, Solana signature, Bridge transfer ID, Circle payment ID, or wallet address; Trace identifies the input, fetches evidence from chain RPCs and provider APIs, and returns one deterministic normalized trace: completed/terminal flags, health, current stage and owner, an evidence-backed diagnosis code with a machine-readable suggested action and retry timing, a knowledge model separating observed facts from inferences and unknowns, and explicit visibility limitations. Anonymous calls trace public onchain data and demo fixtures without any account; provider-connected tracing (Bridge/Circle state) requires an API key whose workspace has provider credentials. Address inputs with multiple recent transfers return a selection_required response rather than silently choosing. Read-only: never moves funds or guarantees beneficiary receipt; while a payment is unresolved the response carries a DO_NOT_RETRY_PAYMENT warning.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceRequest"},"example":{"input":"br_1832f6d09c4b7a","input_type":"auto"}}}},"responses":{"200":{"description":"Trace result or address selection","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TraceResponse"},{"$ref":"#/components/schemas/SelectionResponse"}]},"example":{"schema_version":"1.0","request_id":"req_8fk2n1qpw04m","result":"trace","trace":{"trace_id":"tr_bubz9j0ccvzij8ux","schema_version":"1.0","generated_at":"2026-09-05T23:15:09.202Z","source_input":{"type":"bridge_transfer_id","value":"br_1832f6d09c4b7a"},"visibility":"full","payment":{"asset":"USDC","amount":"12400.00","amount_usd":12400,"chain":"base","provider":"bridge","provider_external_id":"br_1832f6d09c4b7a","from":"0xc751e63f9b36cf2d018374d625162d46ee6fc55b","to":"0x3d7b2b725ee5f45184595b1081e4cf4c03130f59","flow_label":"USDC to MXN payout"},"state":{"normalized_status":"provider_processing","health":"delayed","current_stage":"provider_processing","terminal":false,"completed":false,"current_owner":"provider","chain":{"observed":true,"succeeded":true,"finalized":true},"provider":{"observed":true,"state":"provider_processing"}},"timing":{"started_at":"2026-09-05T22:36:09.202Z","last_event_at":"2026-09-05T22:38:09.202Z","elapsed_seconds":2340,"stage_elapsed_seconds":2220,"delay_seconds":1320},"diagnosis":{"code":"PROVIDER_STAGE_DELAYED","severity":"warning","confidence":"high","summary":"Onchain settlement completed, but the payment remains pending at the provider stage.","explanation":"Onchain settlement completed successfully 38 minutes ago, but Bridge still reports \"payment_submitted\". This stage has been pending longer than the configured threshold (15 minutes).","suggested_action":{"code":"ESCALATE_PROVIDER","reason_code":"PROVIDER_STAGE_DELAYED","reason":"Check payout status with Bridge or escalate ID br_1832f6d09c4b7a to payment operations.","provider":"bridge","external_id":"br_1832f6d09c4b7a","transaction_hash":null,"retry_after_seconds":null,"missing":null},"evidence_ids":["ev_dra7k13qjnv3","ev_3hw61z8jfn2m","ev_nacdl8yxftet"]},"correlation":{"level":"exact","score":1,"factors":[{"type":"transaction_hash","matched":true,"weight":1},{"type":"amount","matched":true,"weight":0.3},{"type":"wallet","matched":true,"weight":0.3},{"type":"timestamp","matched":true,"weight":0.2},{"type":"asset","matched":true,"weight":0.1},{"type":"chain","matched":true,"weight":0.1}]},"knowledge":{"observed":[{"code":"ONCHAIN_FINALIZED","evidence_ids":["ev_3hw61z8jfn2m","ev_nacdl8yxftet"]},{"code":"PROVIDER_PROCESSING","evidence_ids":["ev_dra7k13qjnv3"]},{"code":"PAYMENT_CORRELATED","evidence_ids":["ev_dra7k13qjnv3","ev_3hw61z8jfn2m","ev_nacdl8yxftet"]}],"inferred":[{"code":"PROVIDER_STAGE_DELAYED","confidence":"high","evidence_ids":["ev_dra7k13qjnv3","ev_3hw61z8jfn2m","ev_nacdl8yxftet"]}],"unknown":[{"code":"BENEFICIARY_BANK_CREDIT"}]},"warnings":[{"code":"DO_NOT_RETRY_PAYMENT","message":"This payment's state is unresolved. Do not issue a new payment for the same obligation; it could duplicate funds. Re-check state or escalate instead."}],"stages":[{"id":"st_k8yi2dmyhktv","type":"initiated","status":"complete","chain":null,"provider":"bridge","summary":"Payment initiated with Bridge","started_at":"2026-09-05T22:36:09.202Z","completed_at":"2026-09-05T22:36:09.202Z","evidence_ids":["ev_dra7k13qjnv3"]},{"id":"st_0frvuj2pvgoo","type":"funds_received","status":"complete","chain":null,"provider":"bridge","summary":"Funds received by Bridge","started_at":"2026-09-05T22:36:09.202Z","completed_at":"2026-09-05T22:38:09.202Z","evidence_ids":["ev_dra7k13qjnv3"]},{"id":"st_o0jj2o602he6","type":"onchain_submitted","status":"complete","chain":"base","provider":null,"summary":"USDC transfer submitted on Base","started_at":"2026-09-05T22:37:09.202Z","completed_at":"2026-09-05T22:37:09.202Z","evidence_ids":["ev_3hw61z8jfn2m"]},{"id":"st_lx427a1chl35","type":"onchain_confirmed","status":"complete","chain":"base","provider":null,"summary":"USDC transferred on Base","started_at":"2026-09-05T22:37:09.202Z","completed_at":"2026-09-05T22:37:09.202Z","evidence_ids":["ev_3hw61z8jfn2m","ev_nacdl8yxftet"]},{"id":"st_3gie9vkl701w","type":"onchain_finalized","status":"complete","chain":"base","provider":null,"summary":"Base finalized","started_at":"2026-09-05T22:37:09.202Z","completed_at":"2026-09-05T22:37:09.202Z","evidence_ids":["ev_3hw61z8jfn2m"]},{"id":"st_l41rbpbg9x87","type":"provider_processing","status":"pending","chain":null,"provider":"bridge","summary":"Bridge is processing the payout","started_at":"2026-09-05T22:38:09.202Z","completed_at":null,"evidence_ids":["ev_dra7k13qjnv3"]}],"evidence":[{"id":"ev_dra7k13qjnv3","source":"bridge_api","type":"bridge_payment","observed_at":"2026-09-05T22:38:09.202Z","raw_status":"payment_submitted","external_id":"br_1832f6d09c4b7a","transaction_hash":"0x84e8bdf02f386ce15872f0e4c64542479af3dc1de435b6b8d08db0b4f58ad21f","chain":null,"block":null,"confirmations":null,"metadata":{"id":"br_1832f6d09c4b7a","state":"payment_submitted","amount":"12400.00","on_behalf_of":"cus_demo","source":{"payment_rail":"base","currency":"usdc"},"destination":{"payment_rail":"wire","currency":"mxn"}}},{"id":"ev_3hw61z8jfn2m","source":"base_rpc","type":"base_transaction","observed_at":"2026-09-05T22:37:09.202Z","raw_status":"finalized","external_id":null,"transaction_hash":"0x84e8bdf02f386ce15872f0e4c64542479af3dc1de435b6b8d08db0b4f58ad21f","chain":"base","block":null,"confirmations":1140,"metadata":{"blockNumber":"0x1655c81","confirmations":1140,"transactionHash":"0x84e8bdf02f386ce15872f0e4c64542479af3dc1de435b6b8d08db0b4f58ad21f","status":"0x1","logs":["<decoded Transfer event omitted>"]}},{"id":"ev_nacdl8yxftet","source":"base_rpc","type":"usdc_transfer_event","observed_at":"2026-09-05T22:37:09.202Z","raw_status":null,"external_id":null,"transaction_hash":"0x84e8bdf02f386ce15872f0e4c64542479af3dc1de435b6b8d08db0b4f58ad21f","chain":"base","block":null,"confirmations":null,"metadata":{"from":"0xc751e63f9b36cf2d018374d625162d46ee6fc55b","to":"0x3d7b2b725ee5f45184595b1081e4cf4c03130f59","amount":"12400.00"}}],"limitations":[{"code":"NO_DOWNSTREAM_BANK_VISIBILITY","message":"Trace can verify provider submission and status but cannot confirm beneficiary bank credit."}],"summary":{"headline":"Payment delayed at provider","detail":"Onchain settlement completed successfully 38 minutes ago, but Bridge still reports \"payment_submitted\". This stage has been pending longer than the configured threshold (15 minutes)."}}}}}},"400":{"description":"Invalid request body or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, unknown, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Input or trace not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unsupported input or provider not connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/traces/{id}":{"get":{"operationId":"getTrace","summary":"Retrieve an existing trace","description":"Returns a previously generated trace in the canonical representation. Workspace-owned traces require authentication as that workspace.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"tr_l6umm9ua5w2miqg4"}],"responses":{"200":{"description":"The trace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceResponse"}}}},"400":{"description":"Invalid request body or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, unknown, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Input or trace not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unsupported input or provider not connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/traces":{"get":{"operationId":"listTraces","summary":"List workspace traces","description":"Authenticated only. Lists the workspace's saved traces, newest first.","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"health","in":"query","schema":{"type":"string"}},{"name":"chain","in":"query","schema":{"type":"string"}},{"name":"provider","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Traces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceListResponse"}}}},"400":{"description":"Invalid request body or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, unknown, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Input or trace not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unsupported input or provider not connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/public/traces/{shareId}":{"get":{"operationId":"getSharedTrace","summary":"Retrieve a publicly shared trace","description":"Returns a trace that was explicitly shared via a public link. No authentication required; workspace metadata is redacted.","parameters":[{"name":"shareId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The shared trace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceResponse"}}}},"400":{"description":"Invalid request body or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, unknown, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Input or trace not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unsupported input or provider not connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream data source unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Workspace API key, e.g. Authorization: Bearer tr_live_... Create keys under workspace settings. Scope: trace:read."}},"schemas":{"TraceRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"input":{"type":"string","minLength":1,"maxLength":200},"input_type":{"default":"auto","type":"string","enum":["auto","base_tx_hash","solana_signature","bridge_transfer_id","circle_payment_id","base_address","solana_address"]}},"required":["input","input_type"],"additionalProperties":false},"TraceResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"1.0"},"request_id":{"type":"string"},"result":{"type":"string","const":"trace"},"trace":{"type":"object","properties":{"trace_id":{"type":"string"},"schema_version":{"type":"string","const":"1.0"},"generated_at":{"type":"string"},"source_input":{"type":"object","properties":{"type":{"type":"string","enum":["base_tx_hash","solana_signature","bridge_transfer_id","circle_payment_id","base_address","solana_address"]},"value":{"type":"string"}},"required":["type","value"],"additionalProperties":false},"visibility":{"type":"string","enum":["full","partial","chain_only","provider_only","unknown"]},"payment":{"type":"object","properties":{"asset":{"type":"string","const":"USDC"},"amount":{"type":["string","null"]},"amount_usd":{"type":["number","null"]},"chain":{"anyOf":[{"type":"string","enum":["base","solana"]},{"type":"null"}]},"provider":{"anyOf":[{"type":"string","enum":["bridge","circle"]},{"type":"null"}]},"provider_external_id":{"type":["string","null"]},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"flow_label":{"type":["string","null"]}},"required":["asset","amount","amount_usd","chain","provider","provider_external_id","from","to","flow_label"],"additionalProperties":false},"state":{"type":"object","properties":{"normalized_status":{"type":"string","enum":["unknown","initiated","funds_received","onchain_pending","onchain_finalized","provider_processing","completed","failed"]},"health":{"type":"string","enum":["healthy","delayed","failed","unknown"]},"current_stage":{"anyOf":[{"type":"string","enum":["initiated","funds_received","onchain_submitted","onchain_confirmed","onchain_finalized","provider_processing","payout_submitted","completed","failed","unknown"]},{"type":"null"}]},"terminal":{"type":"boolean"},"completed":{"type":["boolean","null"]},"current_owner":{"type":"string","enum":["chain","provider","sender","recipient","unknown"]},"chain":{"type":"object","properties":{"observed":{"type":"boolean"},"succeeded":{"type":["boolean","null"]},"finalized":{"type":["boolean","null"]}},"required":["observed","succeeded","finalized"],"additionalProperties":false},"provider":{"type":"object","properties":{"observed":{"type":"boolean"},"state":{"anyOf":[{"type":"string","enum":["initiated","funds_received","provider_processing","payout_submitted","completed","failed","unknown"]},{"type":"null"}]}},"required":["observed","state"],"additionalProperties":false}},"required":["normalized_status","health","current_stage","terminal","completed","current_owner","chain","provider"],"additionalProperties":false},"timing":{"type":"object","properties":{"started_at":{"type":["string","null"]},"last_event_at":{"type":["string","null"]},"elapsed_seconds":{"type":["number","null"]},"stage_elapsed_seconds":{"type":["number","null"]},"delay_seconds":{"type":"number"}},"required":["started_at","last_event_at","elapsed_seconds","stage_elapsed_seconds","delay_seconds"],"additionalProperties":false},"diagnosis":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["PAYMENT_COMPLETED","ONCHAIN_PENDING","ONCHAIN_DELAYED","ONCHAIN_FAILED","ONCHAIN_SETTLED","FUNDS_RECEIVED_NO_ONCHAIN","PROVIDER_AWAITING_FUNDS","PROVIDER_PROCESSING","PROVIDER_STAGE_DELAYED","PROVIDER_FAILED","PARTIAL_VISIBILITY","UNKNOWN_STATE"]},"severity":{"type":"string","enum":["info","warning","error"]},"confidence":{"type":"string","enum":["low","medium","high"]},"summary":{"type":"string"},"explanation":{"type":"string"},"suggested_action":{"type":"object","properties":{"code":{"type":"string","enum":["NONE","WAIT","RETRY_LOOKUP","CHECK_PROVIDER","ESCALATE_PROVIDER","CHECK_CHAIN","REVIEW_TRANSACTION_ERROR","REQUEST_MORE_INFORMATION"]},"reason_code":{"anyOf":[{"type":"string","enum":["PAYMENT_COMPLETED","ONCHAIN_PENDING","ONCHAIN_DELAYED","ONCHAIN_FAILED","ONCHAIN_SETTLED","FUNDS_RECEIVED_NO_ONCHAIN","PROVIDER_AWAITING_FUNDS","PROVIDER_PROCESSING","PROVIDER_STAGE_DELAYED","PROVIDER_FAILED","PARTIAL_VISIBILITY","UNKNOWN_STATE"]},{"type":"null"}]},"reason":{"type":["string","null"]},"provider":{"anyOf":[{"type":"string","enum":["bridge","circle"]},{"type":"null"}]},"external_id":{"type":["string","null"]},"transaction_hash":{"type":["string","null"]},"retry_after_seconds":{"type":["number","null"]},"missing":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["code","reason_code","reason","provider","external_id","transaction_hash","retry_after_seconds","missing"],"additionalProperties":false},"evidence_ids":{"type":"array","items":{"type":"string"}}},"required":["code","severity","confidence","summary","explanation","suggested_action","evidence_ids"],"additionalProperties":false},{"type":"null"}]},"correlation":{"anyOf":[{"type":"object","properties":{"level":{"type":"string","enum":["exact","strong_inference","weak_inference"]},"score":{"type":"number","minimum":0,"maximum":1},"factors":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["transaction_hash","provider_external_id","amount","wallet","timestamp","asset","chain"]},"matched":{"type":"boolean"},"weight":{"type":"number"}},"required":["type","matched","weight"],"additionalProperties":false}}},"required":["level","score","factors"],"additionalProperties":false},{"type":"null"}]},"knowledge":{"type":"object","properties":{"observed":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["ONCHAIN_PENDING","ONCHAIN_CONFIRMED","ONCHAIN_FINALIZED","ONCHAIN_FAILED","PROVIDER_INITIATED","PROVIDER_FUNDS_RECEIVED","PROVIDER_PROCESSING","PROVIDER_PAYOUT_SUBMITTED","PROVIDER_COMPLETED","PROVIDER_FAILED","PAYMENT_CORRELATED"]},"evidence_ids":{"type":"array","items":{"type":"string"}}},"required":["code","evidence_ids"],"additionalProperties":false}},"inferred":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["PAYMENT_COMPLETED","ONCHAIN_PENDING","ONCHAIN_DELAYED","ONCHAIN_FAILED","ONCHAIN_SETTLED","FUNDS_RECEIVED_NO_ONCHAIN","PROVIDER_AWAITING_FUNDS","PROVIDER_PROCESSING","PROVIDER_STAGE_DELAYED","PROVIDER_FAILED","PARTIAL_VISIBILITY","UNKNOWN_STATE","PAYMENT_CORRELATED"]},"confidence":{"type":"string","enum":["low","medium","high"]},"evidence_ids":{"type":"array","items":{"type":"string"}}},"required":["code","confidence","evidence_ids"],"additionalProperties":false}},"unknown":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["BENEFICIARY_BANK_CREDIT","PROVIDER_STATE","ONCHAIN_STATE","PAYMENT_IDENTITY"]}},"required":["code"],"additionalProperties":false}}},"required":["observed","inferred","unknown"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["DO_NOT_RETRY_PAYMENT"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["initiated","funds_received","onchain_submitted","onchain_confirmed","onchain_finalized","provider_processing","payout_submitted","completed","failed","unknown"]},"status":{"type":"string","enum":["complete","pending","failed","unknown"]},"chain":{"anyOf":[{"type":"string","enum":["base","solana"]},{"type":"null"}]},"provider":{"anyOf":[{"type":"string","enum":["bridge","circle"]},{"type":"null"}]},"summary":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"evidence_ids":{"type":"array","items":{"type":"string"}}},"required":["id","type","status","chain","provider","summary","started_at","completed_at","evidence_ids"],"additionalProperties":false}},"evidence":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["base_rpc","solana_rpc","bridge_api","circle_api","bridge_webhook","circle_webhook"]},"type":{"type":"string"},"observed_at":{"type":["string","null"]},"raw_status":{"type":["string","null"]},"external_id":{"type":["string","null"]},"transaction_hash":{"type":["string","null"]},"chain":{"anyOf":[{"type":"string","enum":["base","solana"]},{"type":"null"}]},"block":{"type":["number","null"]},"confirmations":{"type":["number","null"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["id","source","type","observed_at","raw_status","external_id","transaction_hash","chain","block","confirmations","metadata"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["NO_PROVIDER_CONNECTION","NO_DOWNSTREAM_BANK_VISIBILITY","PROVIDER_UNAVAILABLE","CHAIN_RPC_UNAVAILABLE","CORRELATION_INFERRED"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"summary":{"type":"object","properties":{"headline":{"type":"string"},"detail":{"type":"string"}},"required":["headline","detail"],"additionalProperties":false}},"required":["trace_id","schema_version","generated_at","source_input","visibility","payment","state","timing","diagnosis","correlation","knowledge","warnings","stages","evidence","limitations","summary"],"additionalProperties":false}},"required":["schema_version","request_id","result","trace"],"additionalProperties":false},"SelectionResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"1.0"},"request_id":{"type":"string"},"result":{"type":"string","const":"selection_required"},"message":{"type":"string"},"address":{"type":"string"},"chain":{"type":"string","enum":["base","solana"]},"matches":{"type":"array","items":{"type":"object","properties":{"transaction_hash":{"type":"string"},"chain":{"type":"string","enum":["base","solana"]},"amount":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"block_time":{"type":["string","null"]}},"required":["transaction_hash","chain","amount","from","to","block_time"],"additionalProperties":false}}},"required":["schema_version","request_id","result","message","address","chain","matches"],"additionalProperties":false},"TraceListResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"1.0"},"request_id":{"type":"string"},"result":{"type":"string","const":"trace_list"},"traces":{"type":"array","items":{"type":"object","properties":{"trace_id":{"type":"string"},"schema_version":{"type":"string","const":"1.0"},"generated_at":{"type":"string"},"source_input":{"type":"object","properties":{"type":{"type":"string","enum":["base_tx_hash","solana_signature","bridge_transfer_id","circle_payment_id","base_address","solana_address"]},"value":{"type":"string"}},"required":["type","value"],"additionalProperties":false},"visibility":{"type":"string","enum":["full","partial","chain_only","provider_only","unknown"]},"payment":{"type":"object","properties":{"asset":{"type":"string","const":"USDC"},"amount":{"type":["string","null"]},"amount_usd":{"type":["number","null"]},"chain":{"anyOf":[{"type":"string","enum":["base","solana"]},{"type":"null"}]},"provider":{"anyOf":[{"type":"string","enum":["bridge","circle"]},{"type":"null"}]},"provider_external_id":{"type":["string","null"]},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"flow_label":{"type":["string","null"]}},"required":["asset","amount","amount_usd","chain","provider","provider_external_id","from","to","flow_label"],"additionalProperties":false},"state":{"type":"object","properties":{"normalized_status":{"type":"string","enum":["unknown","initiated","funds_received","onchain_pending","onchain_finalized","provider_processing","completed","failed"]},"health":{"type":"string","enum":["healthy","delayed","failed","unknown"]},"current_stage":{"anyOf":[{"type":"string","enum":["initiated","funds_received","onchain_submitted","onchain_confirmed","onchain_finalized","provider_processing","payout_submitted","completed","failed","unknown"]},{"type":"null"}]},"terminal":{"type":"boolean"},"completed":{"type":["boolean","null"]},"current_owner":{"type":"string","enum":["chain","provider","sender","recipient","unknown"]},"chain":{"type":"object","properties":{"observed":{"type":"boolean"},"succeeded":{"type":["boolean","null"]},"finalized":{"type":["boolean","null"]}},"required":["observed","succeeded","finalized"],"additionalProperties":false},"provider":{"type":"object","properties":{"observed":{"type":"boolean"},"state":{"anyOf":[{"type":"string","enum":["initiated","funds_received","provider_processing","payout_submitted","completed","failed","unknown"]},{"type":"null"}]}},"required":["observed","state"],"additionalProperties":false}},"required":["normalized_status","health","current_stage","terminal","completed","current_owner","chain","provider"],"additionalProperties":false},"timing":{"type":"object","properties":{"started_at":{"type":["string","null"]},"last_event_at":{"type":["string","null"]},"elapsed_seconds":{"type":["number","null"]},"stage_elapsed_seconds":{"type":["number","null"]},"delay_seconds":{"type":"number"}},"required":["started_at","last_event_at","elapsed_seconds","stage_elapsed_seconds","delay_seconds"],"additionalProperties":false},"diagnosis":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["PAYMENT_COMPLETED","ONCHAIN_PENDING","ONCHAIN_DELAYED","ONCHAIN_FAILED","ONCHAIN_SETTLED","FUNDS_RECEIVED_NO_ONCHAIN","PROVIDER_AWAITING_FUNDS","PROVIDER_PROCESSING","PROVIDER_STAGE_DELAYED","PROVIDER_FAILED","PARTIAL_VISIBILITY","UNKNOWN_STATE"]},"severity":{"type":"string","enum":["info","warning","error"]},"confidence":{"type":"string","enum":["low","medium","high"]},"summary":{"type":"string"},"explanation":{"type":"string"},"suggested_action":{"type":"object","properties":{"code":{"type":"string","enum":["NONE","WAIT","RETRY_LOOKUP","CHECK_PROVIDER","ESCALATE_PROVIDER","CHECK_CHAIN","REVIEW_TRANSACTION_ERROR","REQUEST_MORE_INFORMATION"]},"reason_code":{"anyOf":[{"type":"string","enum":["PAYMENT_COMPLETED","ONCHAIN_PENDING","ONCHAIN_DELAYED","ONCHAIN_FAILED","ONCHAIN_SETTLED","FUNDS_RECEIVED_NO_ONCHAIN","PROVIDER_AWAITING_FUNDS","PROVIDER_PROCESSING","PROVIDER_STAGE_DELAYED","PROVIDER_FAILED","PARTIAL_VISIBILITY","UNKNOWN_STATE"]},{"type":"null"}]},"reason":{"type":["string","null"]},"provider":{"anyOf":[{"type":"string","enum":["bridge","circle"]},{"type":"null"}]},"external_id":{"type":["string","null"]},"transaction_hash":{"type":["string","null"]},"retry_after_seconds":{"type":["number","null"]},"missing":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["code","reason_code","reason","provider","external_id","transaction_hash","retry_after_seconds","missing"],"additionalProperties":false},"evidence_ids":{"type":"array","items":{"type":"string"}}},"required":["code","severity","confidence","summary","explanation","suggested_action","evidence_ids"],"additionalProperties":false},{"type":"null"}]},"correlation":{"anyOf":[{"type":"object","properties":{"level":{"type":"string","enum":["exact","strong_inference","weak_inference"]},"score":{"type":"number","minimum":0,"maximum":1},"factors":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["transaction_hash","provider_external_id","amount","wallet","timestamp","asset","chain"]},"matched":{"type":"boolean"},"weight":{"type":"number"}},"required":["type","matched","weight"],"additionalProperties":false}}},"required":["level","score","factors"],"additionalProperties":false},{"type":"null"}]},"knowledge":{"type":"object","properties":{"observed":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["ONCHAIN_PENDING","ONCHAIN_CONFIRMED","ONCHAIN_FINALIZED","ONCHAIN_FAILED","PROVIDER_INITIATED","PROVIDER_FUNDS_RECEIVED","PROVIDER_PROCESSING","PROVIDER_PAYOUT_SUBMITTED","PROVIDER_COMPLETED","PROVIDER_FAILED","PAYMENT_CORRELATED"]},"evidence_ids":{"type":"array","items":{"type":"string"}}},"required":["code","evidence_ids"],"additionalProperties":false}},"inferred":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["PAYMENT_COMPLETED","ONCHAIN_PENDING","ONCHAIN_DELAYED","ONCHAIN_FAILED","ONCHAIN_SETTLED","FUNDS_RECEIVED_NO_ONCHAIN","PROVIDER_AWAITING_FUNDS","PROVIDER_PROCESSING","PROVIDER_STAGE_DELAYED","PROVIDER_FAILED","PARTIAL_VISIBILITY","UNKNOWN_STATE","PAYMENT_CORRELATED"]},"confidence":{"type":"string","enum":["low","medium","high"]},"evidence_ids":{"type":"array","items":{"type":"string"}}},"required":["code","confidence","evidence_ids"],"additionalProperties":false}},"unknown":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["BENEFICIARY_BANK_CREDIT","PROVIDER_STATE","ONCHAIN_STATE","PAYMENT_IDENTITY"]}},"required":["code"],"additionalProperties":false}}},"required":["observed","inferred","unknown"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["DO_NOT_RETRY_PAYMENT"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["initiated","funds_received","onchain_submitted","onchain_confirmed","onchain_finalized","provider_processing","payout_submitted","completed","failed","unknown"]},"status":{"type":"string","enum":["complete","pending","failed","unknown"]},"chain":{"anyOf":[{"type":"string","enum":["base","solana"]},{"type":"null"}]},"provider":{"anyOf":[{"type":"string","enum":["bridge","circle"]},{"type":"null"}]},"summary":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"evidence_ids":{"type":"array","items":{"type":"string"}}},"required":["id","type","status","chain","provider","summary","started_at","completed_at","evidence_ids"],"additionalProperties":false}},"evidence":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["base_rpc","solana_rpc","bridge_api","circle_api","bridge_webhook","circle_webhook"]},"type":{"type":"string"},"observed_at":{"type":["string","null"]},"raw_status":{"type":["string","null"]},"external_id":{"type":["string","null"]},"transaction_hash":{"type":["string","null"]},"chain":{"anyOf":[{"type":"string","enum":["base","solana"]},{"type":"null"}]},"block":{"type":["number","null"]},"confirmations":{"type":["number","null"]},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["id","source","type","observed_at","raw_status","external_id","transaction_hash","chain","block","confirmations","metadata"],"additionalProperties":false}},"limitations":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["NO_PROVIDER_CONNECTION","NO_DOWNSTREAM_BANK_VISIBILITY","PROVIDER_UNAVAILABLE","CHAIN_RPC_UNAVAILABLE","CORRELATION_INFERRED"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"summary":{"type":"object","properties":{"headline":{"type":"string"},"detail":{"type":"string"}},"required":["headline","detail"],"additionalProperties":false}},"required":["trace_id","schema_version","generated_at","source_input","visibility","payment","state","timing","diagnosis","correlation","knowledge","warnings","stages","evidence","limitations","summary"],"additionalProperties":false}},"count":{"type":"number"}},"required":["schema_version","request_id","result","traces","count"],"additionalProperties":false},"ErrorResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"schema_version":{"type":"string","const":"1.0"},"request_id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_REQUEST","UNSUPPORTED_INPUT","INPUT_NOT_FOUND","PROVIDER_NOT_CONNECTED","SOURCE_UNAVAILABLE","RATE_LIMITED","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","INTERNAL_ERROR"]},"message":{"type":"string"},"retryable":{"type":"boolean"},"retry_after_seconds":{"type":"number"},"suggested_next_step":{"type":"string"},"missing":{"type":"array","items":{"type":"string"}},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","retryable"],"additionalProperties":false}},"required":["schema_version","request_id","error"],"additionalProperties":false}}},"x-error-codes":["INVALID_REQUEST","UNSUPPORTED_INPUT","INPUT_NOT_FOUND","PROVIDER_NOT_CONNECTED","SOURCE_UNAVAILABLE","RATE_LIMITED","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","INTERNAL_ERROR"]}