> For the complete documentation index, see [llms.txt](https://docs.ospree.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ospree.io/developers/blockchain-analytics/openapi/addresses.md).

# Addresses

Screen blockchain addresses and manage the screening results.

## GET /api/v2/analytics/chains/{chain}/addresses/{address}/details

> Get Address Verification Details

```json
{"openapi":"3.1.0","info":{"title":"Ospree Address API","version":"2.0.0"},"tags":[{"name":"Addresses","description":"Screen blockchain addresses and manage the screening results."}],"servers":[{"url":"https://dev-api.ospree.io","description":"Development"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ApiFailResponse":{"properties":{"status":{"type":"string","title":"Status","default":"fail"},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["message"],"title":"ApiFailResponse","description":"*summary*: Api fail response model"},"ApiErrorResponse":{"properties":{"status":{"type":"string","title":"Status","default":"error"},"code":{"type":"integer","title":"Code","description":"Duplicates the HTTP status; use `error_code`. Removed in v3."},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["code","message"],"title":"ApiErrorResponse","description":"*summary*: Api error response model"}}},"paths":{"/api/v2/analytics/chains/{chain}/addresses/{address}/details":{"get":{"tags":["Addresses"],"summary":"Get Address Verification Details","operationId":"Get_address_verification_details_api_v2_analytics_chains__chain__addresses__address__details_get","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","title":"Address"}},{"name":"chain","in":"path","required":true,"schema":{"type":"string","title":"Chain"}}],"responses":{"200":{"description":"The verification and custody state held for this address.","content":{"application/json":{"schema":{}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```

## List Wallet Verification Evidence

> Retrieve the retained wallet-control verification evidence for an address: for each redemption attempt, the exact challenge string that was signed, its nonce, the signature and the envelope it was produced under, the address form, and — on bitcoin — the public key. This is the record a VASP files with a supervisor for a self-hosted-wallet transfer, and it is independently re-verifiable without Ospree.\
> \
> A signature proves control of the signing key for this address at the recorded instant. It does not prove that the wallet is self-hosted (a custodian can sign on a user's behalf), and it does not identify the tenant's customer, whom the challenge never names.\
> \
> Wallets verified before evidence retention shipped return an empty list: nothing was retained for them and nothing can be reconstructed.

```json
{"openapi":"3.1.0","info":{"title":"Ospree Address API","version":"2.0.0"},"tags":[{"name":"Addresses","description":"Screen blockchain addresses and manage the screening results."}],"servers":[{"url":"https://dev-api.ospree.io","description":"Development"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ApiSuccessResponse":{"properties":{"status":{"type":"string","title":"Status","default":"success"},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","title":"ApiSuccessResponse","description":"*summary*: Api success response model"},"ApiFailResponse":{"properties":{"status":{"type":"string","title":"Status","default":"fail"},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["message"],"title":"ApiFailResponse","description":"*summary*: Api fail response model"},"ApiErrorResponse":{"properties":{"status":{"type":"string","title":"Status","default":"error"},"code":{"type":"integer","title":"Code","description":"Duplicates the HTTP status; use `error_code`. Removed in v3."},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["code","message"],"title":"ApiErrorResponse","description":"*summary*: Api error response model"}}},"paths":{"/api/v2/analytics/chains/{chain}/addresses/{address}/verifications":{"get":{"tags":["Addresses"],"summary":"List Wallet Verification Evidence","description":"Retrieve the retained wallet-control verification evidence for an address: for each redemption attempt, the exact challenge string that was signed, its nonce, the signature and the envelope it was produced under, the address form, and — on bitcoin — the public key. This is the record a VASP files with a supervisor for a self-hosted-wallet transfer, and it is independently re-verifiable without Ospree.\n\nA signature proves control of the signing key for this address at the recorded instant. It does not prove that the wallet is self-hosted (a custodian can sign on a user's behalf), and it does not identify the tenant's customer, whom the challenge never names.\n\nWallets verified before evidence retention shipped return an empty list: nothing was retained for them and nothing can be reconstructed.","operationId":"List_wallet_verification_evidence_api_v2_analytics_chains__chain__addresses__address__verifications_get","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","description":"Blockchain network name.","title":"Chain"},"description":"Blockchain network name."},{"name":"address","in":"path","required":true,"schema":{"type":"string","description":"Unique blockchain identifier.","title":"Address"},"description":"Unique blockchain identifier."}],"responses":{"200":{"description":"Retained wallet-control evidence for this address, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccessResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"422":{"description":"Unprocessable Entity - Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```

## Retrieve Address

> Returns an screening result for the requesting address hash or referral id.

```json
{"openapi":"3.1.0","info":{"title":"Ospree Address API","version":"2.0.0"},"tags":[{"name":"Addresses","description":"Screen blockchain addresses and manage the screening results."}],"servers":[{"url":"https://dev-api.ospree.io","description":"Development"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ApiFailResponse":{"properties":{"status":{"type":"string","title":"Status","default":"fail"},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["message"],"title":"ApiFailResponse","description":"*summary*: Api fail response model"},"ApiErrorResponse":{"properties":{"status":{"type":"string","title":"Status","default":"error"},"code":{"type":"integer","title":"Code","description":"Duplicates the HTTP status; use `error_code`. Removed in v3."},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["code","message"],"title":"ApiErrorResponse","description":"*summary*: Api error response model"}}},"paths":{"/api/v2/analytics/chains/{chain}/addresses/{address}":{"get":{"tags":["Addresses"],"summary":"Retrieve Address","description":"Returns an screening result for the requesting address hash or referral id.","operationId":"Retrieve_an_address_api_v2_analytics_chains__chain__addresses__address__get","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","description":"Blockchain network name.","title":"Chain"},"description":"Blockchain network name."},{"name":"address","in":"path","required":true,"schema":{"type":"string","description":"Unique blockchain identifier.","title":"Address"},"description":"Unique blockchain identifier."}],"responses":{"200":{"description":"The most recent screening result held for this address.","content":{"application/json":{"schema":{}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```

## Screen Address

> Screen address hashes to identify potential irregularities or suspicious activities within the\
>         blockchain ecosystem, gaining detailed insights into associated entities and flagged risk indicators.

```json
{"openapi":"3.1.0","info":{"title":"Ospree Address API","version":"2.0.0"},"tags":[{"name":"Addresses","description":"Screen blockchain addresses and manage the screening results."}],"servers":[{"url":"https://dev-api.ospree.io","description":"Development"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ScreenAddressRequestCom":{"properties":{"scan_for_risk":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Scan For Risk","description":"Whether to scan for risk when creating new address","default":false},"provider_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Name","description":"The name of the risk provider to screen with, for example `RDBIG`. Leave it out, or send `null`, to use your business's default risk provider. When sent, it must be a non-empty provider name: a blank or whitespace-only value is rejected with 422."},"is_self_hosted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Self Hosted","description":"Whether the wallet is self-hosted","default":false},"account_ref_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Ref Id","description":"The reference ID of the account"},"link_type":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Link Type","description":"The type of link","default":1}},"type":"object","title":"ScreenAddressRequestCom"},"ApiFailResponse":{"properties":{"status":{"type":"string","title":"Status","default":"fail"},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["message"],"title":"ApiFailResponse","description":"*summary*: Api fail response model"},"ApiErrorResponse":{"properties":{"status":{"type":"string","title":"Status","default":"error"},"code":{"type":"integer","title":"Code","description":"Duplicates the HTTP status; use `error_code`. Removed in v3."},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["code","message"],"title":"ApiErrorResponse","description":"*summary*: Api error response model"}}},"paths":{"/api/v2/analytics/chains/{chain}/addresses/{address}":{"post":{"tags":["Addresses"],"summary":"Screen Address","description":"Screen address hashes to identify potential irregularities or suspicious activities within the\n        blockchain ecosystem, gaining detailed insights into associated entities and flagged risk indicators.","operationId":"Screen_an_address_api_v2_analytics_chains__chain__addresses__address__post","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","minLength":3,"title":"Blockchain network name","description":"Blockchain network name."},"description":"Blockchain network name."},{"name":"address","in":"path","required":true,"schema":{"type":"string","minLength":3,"description":"Unique blockchain identifier.","title":"Address"},"description":"Unique blockchain identifier."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenAddressRequestCom"}}}},"responses":{"200":{"description":"The address was screened and recorded.","content":{"application/json":{"schema":{}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"422":{"description":"Unprocessable Entity - Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"424":{"description":"The provider refused the business's own API key for it. `error_code` says why; `Retry-After` accompanies a rate limit. Only a screen on a key the business connected itself.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"503":{"description":"The business's own provider key could not be read. Only a screen on a key it connected itself.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```

## List Addresses

> Retrieve the paginated list of address screening results based on the requesting business identity

```json
{"openapi":"3.1.0","info":{"title":"Ospree Address API","version":"2.0.0"},"tags":[{"name":"Addresses","description":"Screen blockchain addresses and manage the screening results."}],"servers":[{"url":"https://dev-api.ospree.io","description":"Development"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"ApiFailResponse":{"properties":{"status":{"type":"string","title":"Status","default":"fail"},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["message"],"title":"ApiFailResponse","description":"*summary*: Api fail response model"},"ApiErrorResponse":{"properties":{"status":{"type":"string","title":"Status","default":"error"},"code":{"type":"integer","title":"Code","description":"Duplicates the HTTP status; use `error_code`. Removed in v3."},"message":{"type":"string","title":"Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Stable, machine-readable error code, e.g. `auth.unauthenticated`. Additive-only."},"data":{"anyOf":[{},{"type":"null"}],"title":"Data"}},"type":"object","required":["code","message"],"title":"ApiErrorResponse","description":"*summary*: Api error response model"}}},"paths":{"/api/v2/analytics/chains/{chain}/addresses":{"get":{"tags":["Addresses"],"summary":"List Addresses","description":"Retrieve the paginated list of address screening results based on the requesting business identity","operationId":"List_all_addresses_api_v2_analytics_chains__chain__addresses_get","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","description":"Blockchain network name.","title":"Chain"},"description":"Blockchain network name."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":30,"title":"Size"}},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort"}},{"name":"start_range","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Start Range"}},{"name":"end_range","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Range"}}],"responses":{"200":{"description":"A page of screened addresses for the requesting business.","content":{"application/json":{"schema":{}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"422":{"description":"Unprocessable Entity - Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiFailResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```