---
title: "Discover address ownership information"
method: POST
path: "/entities/{entityDID}/address-ownership/discover"
tags: ["Address Ownership"]
---

# Discover address ownership information

`POST /entities/{entityDID}/address-ownership/discover`

Performs agent discovery for a given blockchain address using multiple methods:
1. Relationships (confirmed/unconfirmed)
2. Hashed Address Service
3. Blockchain Analytics (if configured)

Returns the discovered agent/VASP information, custodian, jurisdiction, relationship status, and ownership proofs (when available).

**Authentication**: Supports both M2M tokens and delegate tokens for automated integrations.

## Path parameters

- `entityDID` string, did, required — Decentralized Identifier (DID)

## Request body

- DiscoverAddressOwnershipBody
  - `asset` string, required
  - `address` string, required

## Response `200`

Address ownership discovered successfully

- object
  - `addressOwnership` object, required
    - `address` string, required
    - `asset` string, required
    - `confidence` 'CONFIRMED' | 'UNCONFIRMED' | 'NOT_FOUND', required
    - `agent` object
      - `did` string, required
      - `name` string, required
      - `jurisdiction` string, required
    - `custodian` object
      - `did` string, required
      - `name` string, required
      - `jurisdiction` string, required
    - `relationship` object
      - `status` string, required
      - `confirmedAt` string, nullable
      - `confirmedBy` string, nullable
      - `proofs` object[]
        - `type` string, required
        - `status` string, required
        - `did` string, required
        - `address` string, required
        - `createdAt` unknown
    - `memoTag` string
    - `source` string, required
    - `discoveredAt` string, date-time, required
    - `responseTimeMs` number, required
  - `meta` object, required
    - `requestId` string, uuid, required
    - `timestamp` string, date-time, required

## Other responses

- `400` — Bad Request - The server could not process the request due to a client error.
- `401` — Unauthorized - Authentication information is missing or invalid.
- `403` — Forbidden - The server understood the request but refuses to authorize it.
- `404` — Not Found - The requested resource could not be found.
- `409` — Conflict - The request could not be completed due to a conflict with the current state of the resource.
- `500` — Internal Server Error - An unexpected condition was encountered on the server.

---

[API](https://skmtc.net/notabene/apis/notabene-api.md) · [All operations](https://skmtc.net/notabene/apis/notabene-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notabene/notabene-api/revisions/70056745a433/schema)