メインコンテンツまでスキップ
API リファレンス

Getting Started

MIZUHIKI Attestors are authorized service operators that can register their KYC-verified users with MIZUHIKI and issue MIZUHIKI Verified SBTs — non-transferable on-chain tokens that signal a wallet address has been verified through an approved attestor. A MIZUHIKI Verified SBT is a trust signal for other services in the ecosystem; it does not replace each regulated service's own onboarding, eligibility checks, or KYC obligations.

Benefits​

  • For your users: A wallet-level verification signal they can present across MIZUHIKI-enabled applications, while each regulated service may still request its own required information.
  • For your application: A reliable, on-chain trust signal that a wallet address belongs to a KYC-verified individual — without exposing personal information on-chain.
  • Ecosystem interoperability: A common verification signal that helps regulated DeFi, RWA, and other compliance-gated services make their own onboarding and eligibility decisions.

Prerequisites​

Become an Approved Attestor​

The MIZUHIKI team must approve MIZUHIKI Attestors before gaining API access. During the approval process, we will review and confirm that your KYC process meets the regulatory requirements of the Act on Prevention of Transfer of Criminal Proceeds.

To apply, contact [email protected].

Once approved, you will receive:

  • An API key to authenticate your backend requests.
  • A Project ID (x-project-id) to scope operations to your project.
注記

All user registration API calls in this guide must be made from your backend. Do not expose your API key in client-side code.

Issuing a MIZUHIKI Verified SBT​

The currently supported use case is minting a MIZUHIKI Verified SBT to a user's EVM wallet address as an on-chain trust signal.

Overview​

1. Register user            →  receive user JWT
2. Issue an SBT
  a. Get signing challenge    →  receive SIWE message parts
  b. User signs message       →  receive signature from user's wallet
  c. Submit signature         →  SBT minted to user's address

Step 1 — Register the User​

Call POST /v1/auth/partner-kyc/register with the user's KYC data. Authenticate with your attestor API key.

POST https://api.mizuhiki.io/v1/auth/partner-kyc/register
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "partnerUserId": "partner-user-123",
  "kycPii": {
    "fullName": "山田 太郎",
    "dateOfBirth": "1990-01-25",
    "address": "東京都港区六本木２丁目３番２号",
    "gender": "male"
  }
}

On success, you receive a user profile and a JWT for that user:

{
  "user": {
    "id": "user-01JY63JZD76DTJH26HF4T2EKYX",
    "status": "verified",
    "linkedAddresses": []
  },
  "authTokens": {
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJhbGci..."
  }
}

Store the accessToken — it is required to authenticate the SBT issuance calls on behalf of this user.

備考

partnerUserId must be the unique identifier for this user in your system. If the same user registers again with the same partnerUserId, the existing account is returned.

Step 2 — Issue an SBT to the User's Wallet​

Issuing an SBT requires the user to prove control of their wallet address. This is done via a ERC-4361 Sign-In With Ethereum (SIWE) challenge.

Step 2a — Get the Signing Challenge​

Call POST /v1/user/address/link/start using the user's accessToken. Include your Project ID and app name as headers.

POST https://api.mizuhiki.io/v1/user/address/link/start
Authorization: Bearer USER_ACCESS_TOKEN
x-project-id: YOUR_PROJECT_ID
x-app-name: defi.example.com

The response contains the fields needed to construct the SIWE message that the user must sign:

{
  "statement": "I agree to a soulbound token (SBT) being issued to my account...",
  "domain": "mizuhiki.io",
  "uri": "api.mizuhiki.io",
  "chainId": 1,
  "nonce": "bPJhMz0WkRhAuETBuQitAg",
  "issuedAt": "2025-12-01T21:34:56.789+09:00",
  "expirationTime": "2025-12-01T22:04:56.789+09:00"
}
警告

The challenge expires at expirationTime. Steps 2b and 2c must be completed before then.

Step 2b — Have the User Sign the Message​

Construct the ERC-4361 SIWE message using the challenge fields and the user's wallet address, then request a signature from the user's wallet.

The message must follow this exact format:

{domain} wants you to sign in with your Ethereum account:
{address}

{statement}

URI: {uri}
Version: 1
Chain ID: {chainId}
Nonce: {nonce}
Issued At: {issuedAt}
Expiration Time: {expirationTime}

Example:

mizuhiki.io wants you to sign in with your Ethereum account:
0x7D74778Fe31741c42C5308FB78ED5373157D51F7

I agree to a soulbound token (SBT) being issued to my account, with both me and MIZUHIKI being authorized to burn it. The SBT will have this metadata: {"name":"Mizuhiki SBT","description":"Proof of Mizuhiki KYC","image":"http://mizuhiki.io/assets/img/mizuhiki_verified.png"}

URI: api.mizuhiki.io
Version: 1
Chain ID: 1
Nonce: bPJhMz0WkRhAuETBuQitAg
Issued At: 2025-12-01T12:34:56.789Z
Expiration Time: 2025-12-01T13:04:56.789Z

Sign this message using the user's EVM wallet private key (e.g., via eth_sign or personal_sign in MetaMask / ethers.js).

Step 2c — Submit the Signature and Mint the SBT​

Call POST /v1/user/address/link with the address, the signed message, the nonce, and the signature.

POST https://api.mizuhiki.io/v1/user/address/link
Authorization: Bearer USER_ACCESS_TOKEN
x-project-id: YOUR_PROJECT_ID
x-app-name: defi.example.com
Content-Type: application/json

{
  "address": "0x7D74778Fe31741c42C5308FB78ED5373157D51F7",
  "message": "mizuhiki.io wants you to sign in with your Ethereum account:\n0x7D74778Fe...",
  "nonce": "bPJhMz0WkRhAuETBuQitAg",
  "signature": "0xdf6aaf23..."
}

On success, MIZUHIKI mints the SBT to the user's address. The response includes the updated user profile with the linked address and a block explorer URL for the mint transaction:

{
  "data": {
    "id": "user-01JY63JZD76DTJH26HF4T2EKYX",
    "status": "verified",
    "linkedAddresses": [
      {
        "id": "user-address-01K1JJ4XVD7X5H3G3Y2EVJXT5J",
        "address": "0x7D74778Fe31741c42C5308FB78ED5373157D51F7",
        "linkedAt": "2025-12-01T12:34:56.789+09:00",
        "sbtUrl": "https://awaji.blockscout.com/tx/0x36b9b1b2...",
        "sbtTokenId": "1",
        "sbtContractAddress": "0x7D74778Fe31741c42C5308FB78ED5373157D51F7"
      }
    ]
  }
}

The user's wallet now holds a MIZUHIKI Verified SBT that can be used as a trust signal by services in the MIZUHIKI ecosystem.

Next Steps​