GET /api/discover

Observability primitive. Lists all attestations known for a subject — useful for browsing history, finding multiple proofs per address, or building dashboards.

Unlike /api/check, this endpoint does not re-verify signatures or recompute metrics. Use /api/verify or /api/check on any returned row if you need authoritative numbers.

GET https://ochk.io/api/discover?addr=bc1q...&limit=25

Query parameters

Param	Required?	Type	Notes
`addr`	one of	string	Bitcoin address.
`id`	one of	string	Attestation ID (hex, 64 chars).
`identity`	one of	string	`protocol:identifier`.
`limit`	optional	int	1–100. Default `50`.

Response (200)

{
  "count": 2,
  "total": 2,
  "attestations": [
    {
      "attestation_id":   "a3f5b8c2…",
      "address":          "bc1q...",
      "scheme":           "bip322",
      "identities":       [
        { "protocol": "github", "identifier": "alice" }
      ],
      "issued_at":        "2026-04-20T12:00:00Z",
      "expires_at":       "2027-04-20T12:00:00Z",
      "verification_url": "https://ochk.io/verify/a3f5b8c2…",
      "relay_hints":      ["wss://relay.damus.io", "wss://relay.nostr.band"]
    },
    { ... }
  ]
}

Fields

Field	Notes
`count`	Number of attestations in `attestations`.
`total`	Number of attestations matched before `limit` truncation.
`attestations[].attestation_id`	64-char hex.
`attestations[].address`	Bitcoin address.
`attestations[].scheme`	`bip322` or `legacy`.
`attestations[].identities`	Self-asserted handle claims.
`attestations[].issued_at`	RFC-3339 UTC.
`attestations[].expires_at`	Optional.
`attestations[].verification_url`	Canonical URL for a full verify UI.
`attestations[].relay_hints`	Relays the publisher suggested.

Ordered most-recent-first by issued_at.

Example

# All attestations bound to github:alice
curl "https://ochk.io/api/discover?identity=github:alice&limit=10"

# Via the SDK
await discover({ identity: 'github:alice', limit: 10 });

Behavior notes

Attestations are discovered via Nostr (kind 30078). A proof that was never published to any relay the service knows about will not appear.
Attestations are deduplicated by attestation_id across relays.
No verification happens. A caller who trusts only /api/discover for decisions is trusting the Nostr relays. For anything gated, pass the returned address or attestation_id to /api/check.

Rate limit

60 req/min per IP.

Status codes

HTTP	Meaning
`200`	Zero or more attestations returned.
`400`	Missing/malformed subject.
`429`	Rate limited.
`500`	Server error.