Connect To a Third Party’s Self-custody
To connect to a user’s self-custody, you first need an account holder.
Our API initiates flows that guide an account holder through the process of connecting their Bitcoin wallet and verifying ownership. Each successful verification produces a claim — a cryptographically verifiable receipt of Bitcoin ownership.
Access Requests
Once you have a valid account holder, the next step is to create an access request. This initiates the process for a user to share their verified Bitcoin ownership (claims) with you.
An access request is how you ask a user to grant visibility into their self-custody. For a user to participate, they must first prove control of their wallet(s) through Hoseki. This ensures the data shared reflects actual ownership — not just access to public information.
To create an access request:
Request:
POST /v1/verify/access_requests/
Access Request Types
There are currently two types of access requests:
-
Sharing – Ongoing access. The user grants continuous visibility into selected claims. Access can be revoked for any claim at any time via the Prove Portal. This model is most similar to how data sharing works with services like Plaid.
-
Statement – One-time access. The user generates and shares a static ownership statement for selected claims. This is ideal for snapshot-style requests (e.g., loan applications or onboarding).
statement access request type is not currently supported via the API. We recommend using the sharing type for all integrations at this time.Permissions
When creating an access request, you must specify which permissions you're requesting. These permissions are shown to the user before they approve the request, ensuring transparency and user control. Each permission defines what specific data the institution will be able to access:
- Balances – View the real-time balance of a claim.
- Statements – Request a statement for a claim, which includes transaction-level history and balance details at a point in time.
Example:
curl https://api.hoseki.app/api/v1/verify/access_requests/ \
--request POST \
--header 'Accept: /' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"type": "sharing",
"account_holder_id": "ah_ezwIXuhcaxO749oDQdZef",
"permissions": [
"balances",
"statements"
]
}'
Once an access request is sent to a valid account holder, they will receive an email notifying them of the new request. When they open Prove, they’ll see a request notification prompting them to review and approve the access.
It will look similar to the example shown below:
Once the user clicks ‘Review’, they’ll see additional details about the access request.
- If they’re already a Hoseki user, they can immediately choose which claims to share (below).
- If they’re new to Hoseki, they’ll be guided through the process of connecting their wallet and verifying ownership before sharing any claims.
Once the user completes the request, you’ll receive a webhook notification confirming that you now have access to their shared claims.
For more information on available webhook events, refer to our webhook documentation.