Skip to main content

​
Quickstart Guide

This guide will walk you through getting started with Crocante, from initial registration to viewing your portfolio and executing your first operation. You’ll be up and running in less than 10 minutes.

​
Prerequisites

Before you begin, make sure you have:
  • A modern web browser (Chrome, Firefox, Safari, or Edge)
  • An email address for account registration
  • Government-issued ID for KYC verification
  • (Optional) Custodian credentials if connecting real assets
Mock Mode: You can skip KYC and custodian setup by using mock mode, which provides simulated data for testing all platform features.

​
Step 1: Choose Your Mode

Crocante supports two operational modes:
1

Mock Mode (Recommended for First-Time Users)

Mock mode allows you to explore all features with simulated data. Perfect for:
  • Learning the platform interface
  • Testing workflows before connecting real assets
  • Development and integration testing
To use mock mode, simply click “Continue with Mock Data” on the login screen.
// Mock mode is activated via login service
// Source: services/api/auth/login-service.ts:7
async loginMock(): Promise<boolean> {
  LocalStorageManager.clearLocalStorage();
  LocalStorageManager.setItem(LocalStorageKeys.SESSION_MODE, "mock");
  if (typeof window !== "undefined") {
    window.dispatchEvent(new CustomEvent("session-mode-changed"));
  }
  return Promise.resolve(true);
}
Mock mode provides:
  • Sample portfolio with BTC, ETH, USDT, and USD holdings
  • Multiple custodians (exchanges, wallets, banks)
  • Full access to staking, credit, governance, and custody features
2

Real Mode (For Live Asset Management)

Real mode connects to backend APIs and manages actual assets. Use this for:
  • Managing real cryptocurrency and fiat holdings
  • Production use cases
  • Institutional portfolio management
Click “Login” or “Register” to use real mode.

​
Step 2: Register Your Account (Real Mode Only)

Skip this section if you’re using mock mode. Mock mode doesn’t require registration.
The registration process consists of 5 steps to ensure compliance and security:
1

Create Account

Provide your basic account credentials:
  • Email address
  • Password (must meet security requirements)
  • Confirm password
// Registration form location: components/auth/register/steps/account.tsx
// The form validates:
// - Email format
// - Password strength
// - Password confirmation match
Click “Continue” to proceed to email verification.
2

Verify Email (OTP)

An OTP (One-Time Password) will be sent to your email address.
  • Check your email inbox for the verification code
  • Enter the 6-digit code in the OTP field
  • Click “Verify” to confirm your email
// OTP verification component: components/auth/register/steps/otp.tsx
// Features:
// - 6-digit input field
// - Resend OTP functionality
// - Automatic validation on complete
Didn’t receive the code? Click “Resend OTP” to request a new verification code.
3

Personal Information

Complete your profile with required KYC information:
  • Full legal name
  • Date of birth
  • Nationality
  • Residential address
  • Phone number
// Personal info form: components/auth/register/steps/info.tsx
// All fields are validated for:
// - Required field completion
// - Format correctness (dates, phone numbers)
// - Character limits
4

Assets Origin

Declare the origin of your assets for compliance:
  • Select source of funds (e.g., Employment, Business, Investment)
  • Indicate if you are a politically exposed person (PEP)
This information is required for regulatory compliance and anti-money laundering (AML) procedures.
// Assets origin form: components/auth/register/steps/assets-origin.tsx
export interface AssetsOriginConfirmProps {
  assetsOrigin: string;
  politicallyExposed: boolean;
}
5

Upload KYC Documents

Upload required identification documents:
  • Government-issued ID (passport, driver’s license, or national ID)
  • Proof of address (utility bill, bank statement)
  • (Optional) Additional documents as requested
// Document upload component: components/auth/register/steps/documents.tsx
// Supports:
// - Drag-and-drop file upload
// - Multiple file formats (PDF, JPG, PNG)
// - File size validation
Once documents are uploaded, click “Complete Registration” to finish.
Your KYC documents will be reviewed by our compliance team. Account approval typically takes 1-2 business days. You’ll receive an email notification when your account is approved.

​
Step 3: Login to Crocante

After registration approval (or if using mock mode), log in to access the platform:
  1. Navigate to the Crocante login page
  2. Enter your email and password (or click “Mock Mode”)
  3. Click “Sign In”
// Login API endpoint: app/api/auth/login/route.ts:12
export async function POST(req: NextRequest) {
  // 1. Validate credentials against schema
  const parsed = LoginRequestSchema.safeParse(body);
  
  // 2. Authenticate with backend
  const loginUrl = getBackendAuthUrl(env.API_GATEWAY, env.EP_AUTH_LOGIN);
  const res = await fetch(loginUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(parsed.data),
  });
  
  // 3. Set HttpOnly session cookie
  const response = NextResponse.json({ success: true });
  setSessionCookie(response, token);
  return response;
}
Crocante uses HttpOnly cookies for session management. Your session token is never exposed to client-side JavaScript, providing enhanced security against XSS attacks.

​
Step 4: Explore Your Portfolio

After logging in, you’ll automatically be redirected to the Portfolio page, which serves as your main dashboard.

​
Understanding the Portfolio View

The portfolio page consists of three main sections:
1

Consolidated View Header

At the top, you’ll see your Total Balance - the sum of all assets across all custodians.
// Portfolio header: domain/portfolio/components/header.tsx:7
export default function Header() {
  const { totalBalance, isLoading } = usePortfolioData();
  
  return (
    <div className="flex items-center justify-between">
      <h3>Consolidated View</h3>
      <p className="text-2xl font-semibold">
        {totalBalance}
      </p>
    </div>
  );
}
The total balance updates every 15 seconds automatically:
// Polling interval: config/constants.ts:3
export const POLL_PORTFOLIO_DATA_INTERVAL = (1000 * 60 * 1) / 4; // 15 seconds
2

Asset Breakdown & Allocation

Below the header, you’ll find two visualizations:Left Section - Asset Breakdown:
  • Total Cryptocurrencies value
  • Total Currencies (fiat) value
  • Total Commodities value
  • Expandable tables showing individual tokens and currencies
Right Section - Asset Allocation:
  • Pie chart showing percentage distribution
  • Visual breakdown by asset type
  • Interactive chart with hover details
// Portfolio layout: domain/portfolio/portfolio.tsx:8
return (
  <div className="space-y-8">
    <div className="bg-card rounded-lg p-6">
      <Header />
      <div className="grid grid-cols-1 lg:grid-cols-3 gap-8">
        <AssetBreakdown />   {/* Left section */}
        <AssetAllocation />  {/* Right section */}
      </div>
    </div>
    <TabsSection />  {/* Bottom section */}
  </div>
);
3

Custodian Tables (Tabs)

The bottom section provides detailed views of your assets across different custodian types:
  • Banks: Fiat currency holdings in traditional banks
  • Custodians: Digital asset custody solutions
  • Exchanges: Assets held on cryptocurrency exchanges
  • Internal Wallets: Self-custody wallet balances
  • OTC Desks: Holdings with over-the-counter trading desks
Each tab shows:
  • Custodian name
  • Assets held
  • Current balance
  • Last update timestamp

​
Step 5: Perform Your First Operation

Now that you can see your portfolio, let’s execute your first operation. We’ll walk through making a deposit.

​
Making a Deposit

1

Access Deposit Modal

From the portfolio page header, click the “Deposit” button (or use the quick action menu).
// Custom header with actions: domain/portfolio/components/custom-additional-header.tsx
// Provides quick access to:
// - Deposit
// - Send
// - Swap
// - Stake
2

Select Token & Network

In the deposit modal:
  1. Select Token: Choose the cryptocurrency you want to deposit (e.g., BTC, ETH, USDT)
  2. Select Network: Choose the blockchain network (e.g., Bitcoin, Ethereum, Polygon)
  3. Select Custodian: Choose where to deposit the funds
// Deposit modal: domain/portfolio/components/header-actions/deposit-modal.tsx
// Uses the deposit address hook to fetch address
// Source: services/hooks/use-deposit-address.ts
3

Get Deposit Address

After making your selections, Crocante will generate a deposit address and QR code.
  • Copy the address to your clipboard
  • Or scan the QR code with your mobile wallet
  • Send funds from an external wallet or exchange
Important: Always verify the network matches your sending wallet. Sending assets on the wrong network may result in permanent loss of funds.
4

Confirm Transaction

After sending funds:
  • Your transaction will appear in the Activity page
  • Portfolio balances will update automatically (within 15 seconds)
  • You can track transaction status and confirmations
// Activity tracking: services/hooks/use-activity.ts
// Polls every 5 minutes for activity updates
export const POLL_ACTIVITY_DATA_INTERVAL = 1000 * 60 * 5;

​
Other Common Operations

Send

Transfer assets between custodians or to external addresses
  • Select token and amount
  • Choose source custodian
  • Enter destination address or select internal custodian
  • Confirm and execute

Swap

Exchange one cryptocurrency for another
  • Select source token and amount
  • Select destination token
  • Review real-time quote
  • Execute swap with one click

Stake

Earn yield on your crypto holdings
  • Navigate to Staking page
  • Select staking type and validator
  • Choose amount to stake
  • Confirm staking transaction

Request Credit

Borrow against your digital assets
  • Navigate to Credit page
  • Select collateral asset
  • Choose loan terms
  • Submit loan request

​
Step 6: Explore Additional Features

You’re now familiar with the basics! Continue exploring Crocante: The left sidebar provides access to all platform modules: 
// Menu items configuration: components/layout/nav-bar.tsx:24
export const MENU_ITEMS = [
  { icon: Building2, label: "Portfolio", id: "portfolio" },
  { icon: STAKE_ICON, label: "Staking", id: "staking" },
  { icon: CreditCard, label: "Credit", id: "credit" },
  { icon: Logs, label: "Activity", id: "activity" },
];

// Mock mode includes additional features:
export const MENU_ITEMS_MOCK = [
  /* ...core items... */
  { icon: Lock, label: "Custody", id: "custody" },
  { icon: Zap, label: "Invest", id: "invest" },
  { icon: Shield, label: "Governance", id: "governance" },
  { icon: Activity, label: "Reports", id: "reports" },
  { icon: Cog, label: "Settings", id: "settings" },
  { icon: FileText, label: "RFQ Manager", id: "rfq-manager" },
];

​
User Profile & Settings

Access your user profile from the sidebar:
  • View your full name and email
  • Logout from your account
  • (Mock mode) Access settings page for preferences
// Session management: context/session-provider.tsx:75
export function useSession() {
  const context = useContext(SessionContext);
  // Provides: isSignedIn, user, isLoading, logout, setToken
  return context;
}

​
Understanding Data Flow

Crocante uses React Query for efficient data fetching and caching: 
// Portfolio data hook: domain/portfolio/hooks/use-portfolio-data.tsx:26
export function usePortfolioData() {
  const { user } = useSession();
  const userId = user?.id.toString() || "";

  const { data: portfolioData, isLoading } = usePortfolio(
    userId,
    POLL_PORTFOLIO_DATA_INTERVAL  // Refetch every 15 seconds
  );

  // Returns:
  // - totalBalance, cryptocurrencies, currencies, commodities
  // - banksData, custodiansData, exchangesData
  // - tokensOptions, fromOptions, toOptions (for dropdowns)
  // - isLoading state
}
Performance: React Query automatically caches data for 5 minutes and refetches in the background. This provides a fast, responsive experience while keeping data up-to-date.

​
Session Management

Your session is managed automatically:
  • Session Duration: Configurable server-side
  • Auto Renewal: Sessions renew automatically in the background
  • Expiry Warning: You’ll be notified before session expiration
  • Auto Logout: Automatic logout on expiry with modal notification
// Session provider polls user data every 5 minutes: context/session-provider.tsx:28
const { data: user, isLoading, isError } = useUser(
  POLL_USER_DATA_INTERVAL  // 5 minutes
);

// Session expiry listener: context/auth-expired-listener.tsx
// Displays modal when session expires

​
Troubleshooting

​
Common Issues

  • Check your internet connection
  • Verify you’re logged in (check session status)
  • Try refreshing the page (Cmd/Ctrl + R)
  • Clear browser cache and cookies if issues persist
  • Ensure you’ve selected both token and network
  • Verify the custodian supports the selected network
  • Check browser console for errors (F12)
  • Contact support if the issue persists
  • This may indicate network issues preventing session renewal
  • Check your firewall/VPN settings
  • Ensure cookies are enabled in your browser
  • Try a different browser or incognito mode
  • Clear browser localStorage
  • Ensure you clicked “Continue with Mock Data” not “Login”
  • Check browser console for errors
  • Try hard refresh (Cmd/Ctrl + Shift + R)

​
Next Steps

Architecture Deep Dive

Learn about Crocante’s technical architecture, design patterns, and code structure

Portfolio API

Explore portfolio endpoints and asset management APIs

Component Library

Browse reusable UI components and their usage examples

User Guides

Learn how to use platform features and manage your assets
Best Practice: Start with small transactions in mock mode to familiarize yourself with the platform before managing real assets. This helps you understand the workflow without risk.

​
Getting Help

Need assistance?
  • Documentation: Browse our comprehensive docs for detailed guides
  • Support: Contact [email protected] for technical assistance
  • Community: Join our community forum to connect with other users
  • Enterprise: Institutional clients have access to dedicated support channels
Welcome to Crocante! You’re now ready to manage your digital assets with confidence.

Build docs developers (and LLMs) love

Get started for freeTalk to us