---
title: "Wallet trust and safety teaser"
method: GET
path: "/v1/wallets/{address}/trust-safety"
tags: ["wallets"]
---

# Wallet trust and safety teaser

`GET /v1/wallets/{address}/trust-safety`

## Request

- Base URL: `https://satoshidata.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://satoshidata.ai/v1/wallets/{address}/trust-safety`
- Auth: none declared

Free endpoint returning satoshidata.ai's public trust card for a Bitcoin wallet, including historical_flags and the coarse present-state risk_indicator.

## Path parameters

- `address` string, required

## Query parameters

- `view` string, nullable: Optional response view. Set `view=compact` for a smaller agent-oriented payload.

## Response `200`

Wallet trust and safety teaser

- WalletTrustSafetyResponse: Free trust-safety response. The label block is asserted-only. When label.category or label.value is null, consumers should read likely_label.value and likely_label.warning for a hedged lead instead of treating the wallet as having no signal.
  - `kind` 'trust_safety'
  - `address` string, required
  - `access` PublicAccessProjection
    - `tier` string, nullable
    - `auth_mode` string, nullable
    - `auth_header` string, nullable
    - `authorization_scheme` string, nullable
    - `label` string, nullable
  - `address_type` object, required: Parsed Bitcoin address type and support metadata.
  - `label` WalletLabelProjection, required
    - `category` string, nullable: Asserted only when the public evidence meets the verified-source threshold and the label is high confidence. Otherwise this is null; read likely_entity on summary responses or likely_label.value on trust-safety responses for the hedged lead.
    - `value` string, nullable: Asserted only when the public evidence meets the verified-source threshold and the label is high confidence. Otherwise this is null; read likely_entity on summary responses or likely_label.value on trust-safety responses for the hedged lead.
    - `hint` string, nullable: Present when category/value are not asserted but a contextual lead exists. This points to likely_entity, likely_label.value, and explanation fields without promoting them into label.value.
    - `confidence` string, nullable
    - `confidence_tier` 'verified' | 'attributed' | 'clustered' | 'reported', nullable: Public provenance tier for this label source family.
    - `source` string, nullable
    - `source_ref` string, nullable
    - `label` string, nullable: Legacy label alias emitted by wallet projections; null when the asserted value is disputed.
    - `value_disputed` boolean, nullable
    - `category_disputed` boolean, nullable
  - `claim_type` string, nullable: Runtime claim type when a public claim is asserted.
  - `confidence` string, required: Public confidence level for the asserted trust card.
  - `evidence_tier` string, required: Evidence tier backing the public trust card.
  - `confidence_tier` 'verified' | 'attributed' | 'clustered' | 'reported', required: Public provenance authority for verified, attributed, clustered, or reported treatment.
  - `is_verified_identity` boolean, required: True only when confidence_tier is verified; false for attributed, clustered, imported, or reported leads.
  - `attribution` WalletAttributionProjection
    - `source` string, nullable
    - `source_ref` string, nullable
    - `claim_type` string, nullable
    - `independently_verified` false
    - `basis` 'single_source_third_party'
    - `attribution_grain` 'entity' | 'category', required
    - `note` string, required
  - `evidence_types` string[]: Evidence categories behind the public trust card.
  - `source` string, nullable: Public source family for the asserted label, when available.
  - `source_ref` string, nullable: Source reference for the asserted label, when available.
  - `narrative` string, nullable: Short public narrative when one is available.
  - `updated_at` string, nullable: Best-known label update timestamp when available.
  - `caveats` string[]: Customer-visible caveats and scope notes.
  - `cluster_recency` object, nullable: Present only for held-and-public addresses with cluster recency metadata.
  - `examined` boolean, nullable: True when the response includes an examined direct-exposure state; false or omitted for pure address-label lookup results.
  - `examined_source` 'direct-counterparty-exposure' | 'address-label-corpus' | 'batch-direct-trace-deferred', nullable: Machine-readable source for the examined marker or explicit batch trace deferral.
  - `note` string, nullable: Customer-visible scope note for direct exposure, clean-trace, not-assessable, or batch-deferred states.
  - `consensus` WalletConsensusProjection, required
    - `state` string, nullable: Agreement state for the public wallet label signal.
    - `label` string, nullable: Human-readable agreement label for the state.
    - `contributor_count` integer, nullable: Distinct public sources behind the label signal.
    - `label_count` integer, nullable: Total public reports behind the label signal.
    - `has_conflict` boolean, nullable: True when public labels conflict.
  - `assessment` WalletAssessmentProjection, required
    - `state` 'identified' | 'lead' | 'context' | 'unlabeled' | 'unlabeled_checked' | 'direct_exposure' | 'traced_clean' | 'insufficient_history' | 'not_assessable' | 'direct_trace_not_run_in_batch' | 'unknown', nullable: Machine-readable assessment state. Exposure-specific states distinguish direct exposure found, traced clean, not assessable, and explicit batch trace deferral.
    - `headline` string, nullable
    - `label` string, nullable
    - `summary` string, nullable
    - `verdict` string, nullable
    - `caveats` string[]
    - `upgrade_hint` string, nullable
  - `risk` WalletRiskProjection, required
    - `tier` 'low' | 'medium' | 'high' | 'unknown', nullable: Trust-safety risk tier for the current response: low, medium, high, or unknown.
    - `flags` string[]: Machine-readable risk and caveat flags.
    - `summary` string, nullable: Customer-visible risk summary.
    - `scope` 'address_label_lookup' | 'direct_1hop', nullable: Scope of the risk tier: exact-address label lookup or bounded direct 1-hop exposure.
    - `confidence` string, nullable: Confidence label for the signal driving the tier.
    - `source` string, nullable: Public source family for the signal driving the tier.
    - `risk_indicator` 'unknown' | 'neutral' | 'elevated', nullable
    - `risk_tier` string, nullable
    - `signals` string[]
  - `exposure` WalletTrustSafetyExposure
    - `state` 'direct_exposure' | 'traced_clean' | 'not_assessable' | 'label_lookup_only' | 'direct_trace_not_run_in_batch' | 'unknown', required: Exposure-analysis state. `traced_clean` means bounded direct counterparties were checked; `direct_exposure` means a flagged direct counterparty was found; `not_assessable` makes no clean claim; `label_lookup_only` means only the address-label corpus was checked; `direct_trace_not_run_in_batch` is the explicit batch-volume deferral state.
    - `reason` string, nullable: Machine-readable reason when no direct trace result is available.
    - `scope` 'address_label_lookup' | 'direct_1hop', nullable: Scope covered by this exposure object.
    - `tier` 'low' | 'medium' | 'high' | 'unknown', nullable: Exposure-derived tier when applicable.
    - `flags` string[]: Exposure-derived risk and caveat flags.
    - `summary` string, nullable: Customer-visible exposure summary.
    - `categories_checked` string[]: Flagged label categories checked during address-label lookup or direct exposure screening.
    - `counterparties_checked` integer, nullable: Number of direct counterparties checked against flagged labels.
    - `counterparty_count` integer, nullable: Total visible direct counterparties in the bounded window.
    - `transactions_examined` integer, nullable: Number of transactions examined for direct exposure.
    - `missing_transactions` integer, nullable: Transactions unavailable from the chain backend.
    - `history_count` integer, nullable: Wallet-history entries considered before bounding.
    - `partial` boolean, nullable: True when the trace was truncated or otherwise partial.
    - `matched_counterparties` WalletTrustSafetyExposureCounterparty[]: Flagged direct counterparties found by the bounded 1-hop trace.
      - `address` string, required: Direct counterparty address matched during the bounded 1-hop exposure trace.
      - `direction` string, nullable: Human-readable flow direction, such as received funds directly from or sent funds directly to.
      - `directions` string[]: Machine-readable direct-flow directions observed between the screened address and this counterparty.
      - `amount_sat` integer, nullable: Approximate direct-flow amount in satoshis.
      - `amount_btc` number, nullable: Approximate direct-flow amount in BTC.
      - `tx_count` integer, nullable: Count of sampled direct transactions for this counterparty.
      - `sample_txids` string[]: Sample transaction ids supporting the match.
      - `label_category` string, nullable: Matched counterparty label category.
      - `label_value` string, nullable: Matched counterparty label value.
      - `confidence` string, nullable: Confidence of the matched counterparty label.
      - `source_ref` string, nullable: Source reference for the matched counterparty label.
      - `flag` string, nullable: Risk flag derived from the matched counterparty label.
      - `exposure_tier` 'medium' | 'high', nullable: Exposure tier derived from the counterparty label confidence.
      - `caveat` string, nullable: Scope caveat: direct counterparty exposure is not identity or ownership attribution.
    - `methodology` string, nullable: Stable methodology identifier for the exposure trace.
    - `ignored_low_confidence_flagged_counterparties` integer, nullable: Flagged counterparties ignored because the supporting label confidence was below the exposure threshold.
  - `historical_flags` string[]: Exact-address public incident/history tags. Empty array when no seeded flag exists.
  - `risk_indicator` 'unknown' | 'neutral' | 'elevated', nullable: Coarse present-state risk indicator, separate from historical_flags.
  - `surveillance` WalletTrustSafetySurveillance
    - `role` 'operator', nullable: Present as operator when the requested address is itself a known dust-trace service wallet.
    - `entity` string, nullable: Public observation label for the dust-trace operator or cluster.
    - `operator_key` string, nullable: Stable registry key for the observed dust-trace operator; not a real-world identity claim.
    - `target_role` 'also_dust_target', nullable: Present when an operator wallet also appears as a dust target in the loaded event snapshot.
    - `dust_traced_by` string[]: Public observation labels for operators that dusted the requested address.
    - `dust_tx_count` integer, nullable: Count of distinct observed dust transactions for this address in the current event snapshot.
    - `first_dust_height` integer, nullable: Earliest Bitcoin block height among the observed dust events in the current snapshot.
    - `last_dust_height` integer, nullable: Latest Bitcoin block height among the observed dust events in the current snapshot.
    - `earliest_dust_age_days` integer, nullable: Age in days from response generation time to the earliest observed dust event in the loaded event snapshot; this is snapshot-derived, not a live-chain clock.
    - `evidence_tier` string, required: Evidence tier for the surveillance observation, such as inferred or cluster_proof.
    - `caveat` string, nullable: Public informational caveat; this is not compliance, legal, or ownership advice.
  - `likely_label` WalletTrustSafetyLikelyLabel
    - `category` string, nullable: Asserted only when the public evidence meets the verified-source threshold and the label is high confidence. Otherwise this is null; read likely_entity on summary responses or likely_label.value on trust-safety responses for the hedged lead.
    - `value` string, nullable: Asserted only when the public evidence meets the verified-source threshold and the label is high confidence. Otherwise this is null; read likely_entity on summary responses or likely_label.value on trust-safety responses for the hedged lead.
    - `hint` string, nullable: Present when category/value are not asserted but a contextual lead exists. This points to likely_entity, likely_label.value, and explanation fields without promoting them into label.value.
    - `confidence` string, nullable
    - `confidence_tier` 'verified' | 'attributed' | 'clustered' | 'reported', nullable: Public provenance tier for this label source family.
    - `source` string, nullable
    - `source_ref` string, nullable
    - `label` string, nullable
    - `value_disputed` boolean, nullable
    - `category_disputed` boolean, nullable
    - `is_disputed` boolean, required
    - `has_consensus` boolean, nullable
    - `consensus_state` 'disputed' | 'none', nullable
    - `reason` string, nullable
    - `projection` 'top_public_lead', required
    - `evidence_tier` string, nullable
    - `claim_type` string, nullable
    - `label_count` integer, nullable
    - `unique_contributors` integer, nullable
    - `warning` string, nullable
  - `disputed_labels` WalletTrustSafetyDisputedLabel[], nullable: Grouped competing public-label candidates with source attribution when sources disagree.
    - `category` string, nullable: Asserted only when the public evidence meets the verified-source threshold and the label is high confidence. Otherwise this is null; read likely_entity on summary responses or likely_label.value on trust-safety responses for the hedged lead.
    - `value` string, nullable: Asserted only when the public evidence meets the verified-source threshold and the label is high confidence. Otherwise this is null; read likely_entity on summary responses or likely_label.value on trust-safety responses for the hedged lead.
    - `hint` string, nullable: Present when category/value are not asserted but a contextual lead exists. This points to likely_entity, likely_label.value, and explanation fields without promoting them into label.value.
    - `confidence` string, nullable
    - `confidence_tier` 'verified' | 'attributed' | 'clustered' | 'reported', nullable: Public provenance tier for this label source family.
    - `source` string, nullable
    - `source_ref` string, nullable
    - `label` string, nullable
    - `value_disputed` boolean, nullable
    - `category_disputed` boolean, nullable
    - `evidence_tier` string, nullable
    - `claim_type` string, nullable
    - `label_count` integer, nullable
    - `unique_contributors` integer, nullable
    - `evidence_types` string[]
    - `updated_at` string, nullable: Most recent grouped-label timestamp for this candidate.
  - `next_steps` WalletNoLabelNextSteps
    - `premium_adds_data` boolean, required: True when premium wallet endpoints are expected to provide additional label-source data for this address.
    - `premium_note` string, required: Short guidance explaining whether premium adds additional label-source data for this address.
    - `contribute` WalletNoLabelContribute, required
      - `endpoint` string, required
      - `method` 'POST'
      - `cost` 'free'
      - `purpose` string, required
  - `inferred_label` WalletLabelProjection
    - `category` string, nullable: Asserted only when the public evidence meets the verified-source threshold and the label is high confidence. Otherwise this is null; read likely_entity on summary responses or likely_label.value on trust-safety responses for the hedged lead.
    - `value` string, nullable: Asserted only when the public evidence meets the verified-source threshold and the label is high confidence. Otherwise this is null; read likely_entity on summary responses or likely_label.value on trust-safety responses for the hedged lead.
    - `hint` string, nullable: Present when category/value are not asserted but a contextual lead exists. This points to likely_entity, likely_label.value, and explanation fields without promoting them into label.value.
    - `confidence` string, nullable
    - `confidence_tier` 'verified' | 'attributed' | 'clustered' | 'reported', nullable: Public provenance tier for this label source family.
    - `source` string, nullable
    - `source_ref` string, nullable
    - `label` string, nullable: Legacy label alias emitted by wallet projections; null when the asserted value is disputed.
    - `value_disputed` boolean, nullable
    - `category_disputed` boolean, nullable
  - `premium_available` WalletPremiumAvailable, required
    - `additional_sources` integer, required: Additional label sources available through premium wallet detail routes.
    - `has_transaction_history` boolean, required: True when premium wallet history routes have transaction context.
    - `has_contributor_detail` boolean, required: True when premium source detail is available for this wallet.
    - `endpoints` string[], required: Premium wallet endpoints related to this address.
    - `price_per_call_sats` integer, required: Native BTC-denominated reference price for the premium summary call.
    - `access` string, required: Current access model label, such as Public beta or API key.
    - `exposure_analysis` object, nullable: Beta value-add metadata describing whether direct 1-hop exposure analysis is included.
  - `_meta` ResponseMeta, required
    - `endpoint` string, required
    - `freshness` string, nullable
    - `freshness_semantics` 'internal_refresh' | 'source_poll' | 'claim_made', nullable
    - `source` string, required
    - `price_sats` integer, nullable
    - `price_usd` string, nullable
    - `docs` string, nullable
    - `warnings` ResponseWarning[]
      - `code` string, required
      - `message` string, required
    - `pagination` ResponsePagination
      - `offset` integer, required
      - `limit` integer, required
      - `total_alerts` integer, required
      - `next_offset` integer, nullable, required
      - `has_more` boolean, required
    - `view` 'compact', nullable
    - `bitcoin_backend` string, nullable
    - `beta` boolean, nullable
    - `cache_seconds` integer, nullable
    - `cache_ttl_seconds` integer, nullable
    - `cache_status` string, nullable
    - `cache_age_seconds` number, nullable
    - `cache_cached_at` string, nullable
    - `cached` boolean, nullable
    - `cache_policy` string, nullable
    - `compute_ms` integer, nullable
    - `warning` string, nullable
    - `refresh_warning` string, nullable
    - `last_refresh_started_at` string, nullable
    - `last_refresh_completed_at` string, nullable
    - `last_refresh_status` string, nullable
    - `last_refresh_error` string, nullable
    - `last_refresh_duration_ms` integer, nullable
    - `feature_flag` string, nullable
    - `rollout_state` string, nullable
    - `schema_version` string, nullable
    - `methodology_version` string, nullable
    - `materialized_source` string, nullable
    - `max_hops` integer, nullable
    - `retention` string, nullable
    - `not_compliance_advice` boolean, nullable
    - `future_native_price_mode` string, nullable
    - `future_native_price_note` string, nullable
    - `future_native_quote_endpoint` string, nullable
    - `overview_activity_cache` object, nullable
    - `attribution_confidence` string, nullable
    - `generated_at` string, nullable
    - `last_computed` string, nullable
    - `snapshot_generated_at` string, nullable
    - `snapshot_age_seconds` number, nullable
    - `snapshot_stale_after_seconds` integer, nullable
    - `snapshot_status` string, nullable
    - `history_window_basis` string, nullable
    - `total_blocks_last_24h` integer, nullable
    - `field_semantics` object, nullable
    - `semantic_completeness` object, nullable
  - `beta` boolean, required

## Other responses

- `400`: Bad request.
- `404`: Resource not found.
- `405`: Method not allowed.
- `422`: Request validation failed.

---

[API](https://skmtc.dev/satoshidata/apis/satoshidata-agent-api.md) · [All operations](https://skmtc.dev/satoshidata/apis/satoshidata-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/satoshidata/apis/satoshidata-agent-api/revisions/9fc9edc41ac4?raw)