Skip to main content

Overview

Welcome to Freeq! This guide will walk you through integrating the Freeq API to seamlessly create and manage Web3 wallets for your users.

What is "Headless" Wallet Integration?​

This "headless" approach means wallets are provisioned in the background, tied to your existing user accounts. Your users get access to Web3 capabilities without needing to navigate complex crypto onboarding flows, private key management, or seed phrases.

Key Benefits​

  • Zero crypto complexity for your users
  • Seamless onboarding using existing authentication
  • No seed phrases or private key management required
  • Instant Web3 capabilities for any application

How It Works: Core Concepts​

The integration is designed to be simple and robust. Here are the key concepts:

1. Headless Wallets​

When a user signs up or logs in to your platform for the first time, you'll make a single API call to Freeq. We handle the wallet creation process on our side, associating the new wallet with the user's identity (e.g., their email address).

2. JWT-Based Authentication​

Every request to the Freeq API is authenticated using a JWT generated by your system. This proves that the request is coming from a valid, authenticated user on your platform. We validate these tokens using standard OpenID Connect (OIDC) practices.

3. Flexible Processing Options​

Wallet creation can be either synchronous or asynchronous based on your needs:

  • Synchronous: Immediate access to wallet details upon creation
  • Asynchronous: Receive confirmation that the request was accepted, retrieve wallet details later via webhooks or the /signin endpoint

Integration Approaches​

  • Call /createasync for new users
  • Call /signin for returning users
  • Receive wallet details via webhooks
  • Best for production applications

Synchronous Flow​

  • Call /signin for all users (creates wallet if needed)
  • Immediate wallet details in response
  • Simpler for testing and development

Documentation Structure​

We provide two complementary sets of documentation:

REST API Reference​

The complete OpenAPI/Swagger reference for every available endpoint. This is where you can explore routes for authentication, organisations, projects, wallets, contracts, inventory, webhooks, and more. Perfect for testing individual requests or understanding the raw REST interface.

Best for: Direct API integration, testing endpoints, understanding raw HTTP requests

TypeScript SDK Reference​

A higher-level TypeScript SDK built on top of the API. This library simplifies common workflows, wraps responses into a rich object model, and comes with strong typing to make integration with modern projects straightforward. Ideal for developers who want to move fast without losing flexibility.

Best for: Modern web applications, rapid development, type safety

Choose the set of docs that best suits your workflow. You can dive into the low-level details with the API reference, or start building quickly with the SDK. Both are designed to work seamlessly together.

Quick Navigation​

Additional Resources​

Once you understand the integration workflow, explore our comprehensive documentation:

Questions?

Check out our troubleshooting guide for common issues and solutions, or reach out to the Freeq team for support.