Getting Started With Hatchfi API


In this guide, we’ll be walking you through how to set up and test the Hatchfi API using Hatchfi Link. If you don’t already know, Hatchfi Link is our plug-and-play modal UI that makes it easy for your users to connect their crypto accounts to your application with just a few lines of code.

By the end of this guide, you’ll have completed the following:

  • Created a Hatchfi account on Hatchfi

  • Get Hatchfi Link setup with your auth credentials

  • Create your first user account connection with Hatchfi Link

  • Retrieve and access your user's balance object data


  • A Hatchfi account and access to your Hatchfi Dashboard along with your ClientId, API Key and Secret Key

  • Session Token

  • One of your users' UUID that you’d like to authenticate against the Hatchfi API

Component Definitions

  • clientId - used to identify and access your project within Link (found inside your Hatchfi Dashboard)

  • userId - this is the UUID of your user from your database

  • apiKey - used to authenticate to the Hatchfi backend

  • secretKey - used to authenticate to the Hatchfi backend

  • sessionToken - this token is returned once you have authenticated your account and the users account you’d like to connect - TTL = 20 minutes

  • Project - a project is a scoped instance of Hatchfi for your applications, meaning that you can have one or more separate projects or apps within Hatchfi with different users

Creating a Hatchfi account

To create an account

  • Head over to and sign up

  • You will be taken to your dashboard, where you will be able to create a project

  • Click create a project

  • Within your dashboard, you will now have access to your clientId, apiKey, and secretKey - please make sure you write down your secretKey as it will only be available once at the beginning of the project creation

  • Losing your secretKey will disallow all access to your app and you will need to create a new project

  • Once you’ve created your project inside of your Hatchfi Dashboard, you are ready and set to start using Hatchfi

  • Make sure you check out our docs at for more information

Setting up Hatchfi Link

Generate a session token

Upon success, you will receive a session token allowing your user to access Hatchfi Link within your app and log in to their respective providers. See the example return below.

    "userId": "4e22d4b5-0cef-413f-898e-73c3eb6d4921",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIwMDExIiwiaWF0IjoxNjQ5NDA1NzY0LCJleHAiOjE2NDk0MDY5NjR9.l8JVJzLe2NAOSXKZsM2LQHMJrFDlCtQZqSqoSbhuHVs"

From here, you have two choices:

  • Open up an iframe with Hatchfi Link

  • Open up a new window or tab with Hatchfi Link (

Hatchfi Link Flow Diagram

Testing with Hatchfi Link and retrieving your data via Postman or Insomnia

After your session is authenticated, it's time for you to connect your users' wallet, exchange, or protocol. Remember, Hatchfi will automatically create a new user on your behalf if your user doesn't exist yet with you having to touch a thing. Hatchfi Link will look for the userid that you passed in when creating your Link session and if that userid is not recognized, an account for that user is seamlessly created.

Open up your authenticated Hatchfi Link session{your-client-id}&token={users-session-token}

Once you have Hatchfi Link open in your browser, go ahead and add a connection. A successful connection of your users crypto account will look like this:

successful connection of end-user account

From here, it's time to open up Postman, Insomnia, or whatever tool of your choosing. We're going to go ahead and pull our user's account data from Hatchfi that we just added, fully standardized and ready for you to use in whatever crypto-powered financial product you are building!

We're going to pull the balance object data of the user's bitcoin account that we just connected with Hatchfi Link.

Go into your tool and set up the following (we're using Insomnia in this example):

Request type:

  • GET request


Required Headers:

  • X-Hatchfi-Api

  • X-Hatchfi-Secret

  • X-Hatchfi-User-Id

Remember, your API key and secret key can be found in your Hatchfi Dashboard Dashboard.

Your setup should look like this:

Insomnia Headers

Go ahead and hit SEND in Insomnia. The returned result will be a Balance object with a 200OK Balance Object.


Returned data

BOOM! You did it and it literally in less than 10 minutes! You can now use this data in your applications!


After this guide, you should have been able to successfully set up your Hatchfi Link within your application, create a new user, add that user's crypto account, and successfully retrieve your user's data from the Hatchfi database!