Deeproof API Reference

API Overview

The Deeproof Backend API allows external developers, partner protocols, and integrators to interact with the Deeproof identity and KYC system. It provides capabilities to:

• Bind a wallet to a Deeproof identity.
• Submit ZK-KYC proofs.
• Check the verification status of a user.
• Integrate with protocol hooks.

Base URL & Versioning

Base URL: http://localhost:3001

Versioning: Not specified in api.md.

---

Endpoints Documentation

Identity

Bind Identity

Associates a wallet address with a Deeproof identity.

• Method: POST
• Path: /identity/bind

Request Body

Field	Type	Description	Required
walletAddress	string	40-character hex string (Ethereum address)	Yes
identityCommitment	string	The identity commitment string	No

Request Example

{
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "identityCommitment": "123456789..."
}

Success Response (200/201) Response body structure not specified in api.md.

---

Get Identity

Retrieves identity information for a specific wallet.

• Method: GET
• Path: /identity/:walletAddress
• Authentication: Not specified in api.md.

Path Parameters

Parameter	Type	Description	Required
walletAddress	string	Ethereum wallet address (0x...)	Yes

Success Response (200)

{
  ...identityData
}

---

KYC

Submit KYC Proof

Submits ZK-KYC proof metadata and commitment.

• Method: POST
• Path: /kyc/submit
• Authentication: Not specified in api.md.

Request Body

Field	Type	Description	Required
walletAddress	string	Ethereum wallet address	Yes
proofReference	string	Reference to the ZK proof	Yes
commitment	string	The proof commitment	Yes
provider	string	Identity provider (e.g., 'binance')	No
txHash	string	Transaction hash	No
kycScore	number	Score between 0-100	No
solidityParams	object	Parameters for on-chain verification	No

solidityParams Object

Field	Type	Description
a	array	Proof parameter A
b	array	Proof parameter B
c	array	Proof parameter C
input	array	Public inputs

Request Example

{
  "walletAddress": "0x1234...",
  "proofReference": "proof-uuid-123",
  "commitment": "commitment-hash",
  "provider": "binance",
  "txHash": "0xabc...",
  "kycScore": 100,
  "solidityParams": {
    "a": ["..."],
    "b": [["..."]],
    "c": ["..."],
    "input": ["..."]
  }
}

Success Response Not specified in api.md.

---

Get KYC Status

Checks the current KYC status of a wallet.

• Method: GET
• Path: /kyc/status/:walletAddress
• Authentication: Not specified in api.md.

Path Parameters

Parameter	Type	Description	Required
walletAddress	string	Ethereum wallet address	Yes

Success Response (200)

{
  "status": "PENDING",
  "updatedAt": "2023-10-27T10:00:00Z"
}

Note: status can be "PENDING", "VERIFIED", or "REJECTED".

---

Check Verification (Boolean)

Simple check if a wallet is verified.

• Method: GET
• Path: /kyc/verified/:walletAddress
• Authentication: Not specified in api.md.

Path Parameters

Parameter	Type	Description	Required
walletAddress	string	Ethereum wallet address	Yes

Success Response (200)

{
  "verified": true
}

---

Update KYC Status (Internal)

Updates the status of a KYC record.

• Method: PATCH
• Path: /kyc/status/:walletAddress
• Authentication: Internal check (specifics not specified in api.md).

Path Parameters

Parameter	Type	Description	Required
walletAddress	string	Ethereum wallet address	Yes

Request Body

Field	Type	Description	Required
status	string	"PENDING" | "VERIFIED" | "REJECTED"	Yes
txHash	string	Transaction hash	No

Request Example

{
  "status": "VERIFIED",
  "txHash": "0xdef..."
}

Success Response Not specified in api.md.

---

Protocol API (Partner Integration)

Designed for third-party applications (DeFi protocols, RWA platforms, etc.) to validate if a user has completed KYC on Deeproof without accessing sensitive PII.

Check KYC Status

Partners can use this endpoint to gate access or provide tiered services based on a user's Deeproof KYC status.

• URL: /protocol/check/:walletAddress
• Method: GET
• URL Params:
  • walletAddress: Ethereum wallet address to check (e.g., 0x123...)
• Success Response:
  • Code: 200
  • Content:

    {
      "walletAddress": "0x71C...",
      "isVerified": true,       // Main indicator. true = KYC verified, false = pending/rejected/not found
      "kycScore": 100,          // Reputation score (0-100)
      "verifiedAt": "2024-03-20T10:00:00.000Z" // Timestamp of verification (or null)
    }

• Example Usage:

  curl https://api.deeproof.xyz/protocol/check/0xYourWalletAddress

  (Note: Replace domain with actual production URL)

---

Data Models

Identity Data

Structure not fully specified in api.md.

KYC Status Response

Field	Type	Description
status	string	One of "PENDING", "VERIFIED", "REJECTED"
updatedAt	string	Timestamp of the last update

Verification Check Response

Field	Type	Description
verified	boolean	True if the wallet is verified, false otherwise

Error Handling

The API uses standard HTTP status codes.

Code	Description
200	OK - Success
201	Created - Resource successfully created

Specific error codes (400, 401, 404, 500) and error response formats are not specified in api.md.

Rate Limiting & Constraints

Rate limits and size restrictions are not specified in api.md.