REST API Integration

Authenticate a user and fetch their wallets.

This guide helps developers integrate Clique Wallet into their applications using the RESTful API.

Prerequisites

• Access to a Clique Wallet instance

• The Clique Wallet API endpoint URL

• A web application or backend service where you want to integrate Clique Wallet

• Basic understanding of REST APIs and HTTP requests

Basic Setup

1. Configure Your Clique Wallet Endpoint

First, configure your application to point to your Clique Wallet instance:

const WALLET_API_URL = 'https://your-wallet-instance.com';

2. Understand the Authentication Flow

Clique Wallet uses session-based authentication for user-facing applications. When a user successfully authenticates, Clique Wallet sets a secure HTTP-only session cookie that maintains the user's authentication state.

Your First Integration

Step 1: User Authentication

Users can authenticate using various methods. Here's a simple example using email verification:

Request a Verification Code:

curl -X POST https://your-wallet-instance.com/send_verification \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Complete Login:

After the user receives and enters the verification code:

curl -X POST https://your-wallet-instance.com/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "type": "Email",
    "data": {
      "email": "[email protected]",
      "code": "123456"
    }
  }'

Upon successful login, Clique Wallet will:

• Create wallets for all supported blockchains (if they don't exist)

• Set a secure session cookie

• Return user information including wallet addresses

Step 2: Check Session Status

To verify the user is authenticated and get their wallet information:

curl -X GET https://your-wallet-instance.com/session \
  -H "Content-Type: application/json" \
  -b cookies.txt

The response will include:

• User ID

• Wallet addresses for all supported networks (Solana, EVM-compatible chains, etc.)

• Authentication methods bound to the account

Step 3: Get Wallet Addresses

Wallet addresses are automatically created upon first login. You can retrieve them from the session response:

{
  "id": "user-id",
  "wallets": [
    {
      "id": "wallet-id",
      "address": "0x...",
      "network": "Ethereum",
      "wallet_type": "Embedded",
      "wallet_set": "Main"
    },
    {
      "id": "wallet-id",
      "address": "So1...",
      "network": "Solana",
      "wallet_type": "Embedded",
      "wallet_set": "Main"
    }
  ]
}

Step 4: Sign Your First Transaction

To sign a transaction, send the transaction data to the sign endpoint:

curl -X POST https://your-wallet-instance.com/sign \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "address": "0x...",
    "network": "Ethereum",
    "message": "0x...",
    "need_check": true
  }'

The response will include the signature that can be used to submit the transaction to the blockchain.

Authentication Methods

Clique Wallet supports multiple authentication methods:

Social OAuth (Google, X/Twitter, Telegram):

1. Initialize OAuth flow with /oauth/init

2. Redirect user to the OAuth provider

3. Handle callback at /oauth/callback

4. Complete login with /login using the OAuth credentials

External Wallet Connection:

1. Get challenge message from /challenge

2. User signs the challenge with their external wallet

3. Complete login with /login using the signature

Phone Verification: Similar to email verification, but use phone instead of email in the request.

Common Patterns

Checking if User is Logged In:

async function checkAuthStatus() {
  const response = await fetch('https://your-wallet-instance.com/session', {
    credentials: 'include' // Important: include cookies
  });
  
  if (response.ok) {
    const user = await response.json();
    return user;
  }
  return null;
}

Handling Session Expiration:

async function ensureAuthenticated() {
  const user = await checkAuthStatus();
  if (!user) {
    // Redirect to login
    window.location.href = '/login';
    return null;
  }
  return user;
}

Error Handling:

try {
  const response = await fetch('https://your-wallet-instance.com/sign', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    credentials: 'include',
    body: JSON.stringify(signRequest)
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error('Sign error:', error.error);
    // Handle error appropriately
  } else {
    const result = await response.json();
    // Use the signature
  }
} catch (error) {
  console.error('Network error:', error);
}