Fern API - Pooja Shah

[Music] My name is Puja and I'm the founder of Fern. Today I'm going to do a quick workshop on how to get started using the Fern API. In this workshop, we're going to cover four main topics. First, we'll give an overview of what Fern is and how you can use it. We'll then talk about how you can get started as a builder.

We'll go into what some of the core API concepts are in Fern and how builders use Fern in practice in their applications through a number of API examples. And then lastly, we'll talk about how you can get help as you're working on building your projects and integrating Fern into your applications. So, first, what is Fern? Fern is global money movement infrastructure. We built Fern so that builders like you could have access to all of the building blocks you need in order to assemble a fully complete and featurerich crypto application.

Some of the building blocks that are included as part of the fern API include currency exchange. This includes firstparty and third party on-ramps, off-ramps, foreign exchange and crypto swaps. And these currency exchanges work globally. We support more than 10 currencies, fiat currencies for payins and more than 50 currencies for payouts. We also provide wallets.

You can use Fern to provision multi-chain EVM wallets for your customers that offer really seamless UX. Gas sponsorship comes out of the box when you use Fern wallets on all of the chains we support, which today are Arbitum, Base, Ethereum mainet, Optimism, and Polygon. These wallets are also safe multisigs, but they are deployed to a single address on all of the chains that we support. Down the road, we plan to release exciting multi-IG functionality. And this enables you to futureproof the wallets that you're offering your customers while still receiving the benefits that smart contract wallets can offer.

Fern also offers fiat accounts which enable your customers to receive fiat payments and our supported currencies and also make fiat payments. And two features that we have coming soon but which are not currently live in the API today include yield and card issuance. Yield will will enable you, your customers and whoever else you desire to earn revenue on the funds that are at rest in fern wallets and card issuance will enable you to issue branded cards to your customers so that they can spend crypto in their fern provisioned wallets via the cards that you issue to them. Together, these five building blocks we think built a complete stack of financial infrastructure for new companies and new projects that are getting started and want to seamlessly bridge fiat and crypto. Some of the funds flows that are made possible by Fern are depicted in this chart.

So you can see in the center um the set of customer payment accounts and there are many different payment accounts that we support with Fern. Um obviously we support Fern wallets. These are the crypto multi-IG EVM wallets that I previously mentioned that are multi-chain. We also support foreign fiat accounts. We support the ability to register external wallets to the same customer and external bank accounts as well.

And all of these collectively represent the individual customers payment accounts. This customer can be an individual, it can be a business, but we also support outgoing payments and incoming payments from third parties as well. So for the payment accounts that exist and belong to your direct customer, some of the core funds flows that are enabled include currency conversion for firstparty use cases. So this means if your customer wants to on and off ramp between their own accounts, they want to move their own fiat and convert it to crypto or move funds in the other direction, they can do that. Also for your customers payment accounts, we can support in the future, we'll be able to support earning yield on the funds that are at rest in your customers wallet.

But as I mentioned, we're also able to support thirdparty payments into and out of any of your customers accounts. So, your customer is able to receive incoming crypto payments from third parties and incoming fiat payments from third parties as well. Um, and your customer is also able to make outgoing payments both in crypto and in fiat to third parties. All of these funds flows are supported with Fern's infrastructure. today.

As you can imagine, this enables a breath of use cases and funds flows for you in your application and how you decide to leverage the different building blocks that Fern provides to create your ideal user experience. Because Fern can offer so many different types of funds flows, we find that sometimes it can be helpful to for you to get feedback from our team on which pieces of the Fern entire product suite will be most applicable for your application. So once we get to the support section, you can see a little bit more about how to get in touch with our team, but we're always happy to consult on use cases and funds flows and figure out how you can most efficiently use our APIs to enable your ideal user experience. All of the Fern infrastructure and product suite is made possible by our underlying technology that we call the Fern multiplex. At its core, the multiplex has three layers.

There are a set of liquidity providers that we integrate at the base layer of this infrastructure. We have many different liquidity providers for each of the routes that we support. And this includes crypto only bridging and swapping and it also includes fiat on and off ramps. It also includes direct FX. Above the liquidity layer, we have a compliance engine which enables us to ensure that all of the customers that are transacting with our liquidity and currency conversion and payment infrastructure are legitimate parties.

There's no fraud occurring in the system and they are legitimately able and allowed by local regulation to transact with the currencies that we want to give them access to. And then we have a routing engine on top of all this which looks at for each customer that desires to transact with a certain set of routes that they're approved to transact with, what is the optimal way to get from currency A to currency B. We look at factors including cost and speed. And we ultimately decide a route that is going to most effectively get your customers funds from currency A and payment account A to currency B and payment account B. We also have various interfaces that enable different um customer groups.

This includes individuals, businesses, and filters like you to access the multiplex infrastructure. So today we're more focused on the API solution which is what you will likely be using to access the multiplex. But we also have an application which is available at app.fernhq.com.

And in the future we plan to build smart contract interfaces to access this multipplex infrastructure. Today, Fern supports 50 plus fiat currencies via local payment rails. You can see a sampling of the currencies that we support here. Not all of these currencies are supported for both on-ramps and off-ramps. You can go to our docs to get more specific information about which direction is supported for which fiat currency.

It's very clearly denoted in the docs, but we wanted to give you a set a sense of what we support from a fiat currency perspective. Okay, so that's a little bit of an overview of what um you can do with Fern. Now that you're ready to get started, we can show you how to do that. So, the first thing is that you're going to create an an account at dashboard.fernhq.

com. This was very recently released um and it's an exciting new home for our developers who are building with Fern to get access to everything they need to manage their developer instance and their de developer account with Fern. You can create an account um very simply just you can get started. You don't need to talk to a human to do it. As you're going through the onboarding flow, I would suggest that you select the builder tier which has no monthly platform fee.

You can also give us more information about your organization. Some of this um information will be used for branding for some of the hosted forms that we provide that you can optionally choose to use in your application if you'd like. But otherwise, it's just to give us a a bit of a heads up about what you're looking to build so we can see how we can best support you. Once you have created your account in the dashboard, you'll see the ability to create an API key, which you can go ahead and do whenever you're ready to get started. And you'll also see on the homepage of the dashboard a card for a building a billing wallet.

This billing wallet will have a uh an EVM address and it's a wallet that you can fund in USDC and which we will automatically deduct balances from for certain usage events of the API. We don't charge for buil for the builder tier. Most of what you're being charged for is customer usage for certain things um such as KYC and wallet creation. We do not currently charge you directly for transactions because the way that transactional revenue occurs with Fern is that uh for the builder tier is that all of the fees that Fern charges are deducted from the transaction and your customer will see their conver the amount that they receive in their destination payment account deducts deducted uh with the Fern fee already. So you don't have to worry about um transaction fees.

If you choose to create lots of wallets, if you choose to KYC lots of customers, those are events that you will need to pay for. And in order to pay for that, you would need to fund your billing wallet in USDC. So you can see all of that on the Fern dashboard. And the most important resource is our doc site. So you can go to our docs at docs.

fernhq.com. And this will give you an overview of a lot of the information that we're covering in this workshop, but in much more detail, as well as specific API examples that you can sort of copy paste into your application as you're you're learning how everything works. Now, let's go into common API workflows and some of the core concepts that you would need to know to be successful using the Fern API. So, when um this is also this diagram is also in our docs.

When you first get started with Fern, I would suggest actually reading in detail what the core API concepts are. We find that for these types of financial infrastructure solutions, the hardest part could just be understanding what the different API concepts are and just wrapping your head around it so that you can build really the custom use case and ideal UX that you'd like. So the first uh and most important hub of everything in the for an API is the notion of a customer. A customer it can be an individual or a business. Um all you need to do to create a customer is to register the user with their name and email address.

If it's an individual, we ask for first name, last name, and email address. If it's a business, we ask for business name and email address. customers can be created without having to go through any form of KYC. Um, and if they are created without having yet done KYC, then they can still interact with payment accounts, which includes u being able to set up bank accounts and crypto wallets, including Fern wallets for the customer. And they can also interact with um quotes and transactions that are touching crypto only.

In order for your customer to gain access to any of the fiat transacting capabilities and fiat payment accounts that exist in the firm platform, they need to have gone through KYC or KYB and to have been successfully approved. So that's one thing to note. Um but conceptually in this entity relationship mapping, customers are able to have many payment accounts under them. So first you would create a customer. there's a separate process for verifying that customer which we'll talk about in a second.

Um, but a customer can have many payment accounts registered to the customer and those payment accounts can be firstparty payment accounts meaning that those accounts can belong to the customer directly but they can also be thirdparty payment accounts. So, if you anticipate this customer, if you're building um an invoicing application or some sort of payments platform, your customer may have contacts that it's going to be paying or receiving payments from. These would be third parties and you can register the payment accounts of those third parties under your customer entity and just register that specific payment account as a thirdparty payment account. Once um you've registered your customer and you've registered payment accounts, you can use these concepts to interact with quotes. Quotes reference payment accounts.

We are able to also provide exchange rates for certain currency pairs that do not need to reference payment accounts. But when you're ready to actually create a transaction, you first need to create a quote which specifies your source and destination. And the source includes the source payment account and the destination payment account as well. Once a quote has been created for the transaction, the currency exchange or currency or or just payment transaction that you'd like to initiate through Fern, you can then use u create a transaction which references a quote directly. So the sequence of events is you create a quote.

Uh once the quote looks good to you and you can confirm that it looks good, you would then initiate a transaction and a transaction is mapped to a quote one to one. You can only create a transaction once you have a valid quote. The most common workflow that we see with Fern is um with the Fern API is on and off ramping. So the sequence of steps that we see customers need to go through and you don't need to do all of this every time you are initiating an on andoff ramp. Some of these are one-time setup steps and some of these are ongoing steps that would need to happen every time you're interested in initiating a new transaction.

Uh but these are the most common steps that we see that we see um our customers going through. So the first thing is needing to create your customer and again this can be an individual or a business. Once the customers been created they need to be verified. There are two ways to verify customers. You can either submit the KYC data for the customer via our API.

This enables you to create a fully whitelabeled an ideal user customizable user experience for how you want to be collecting this information. It also enables you to collect the data so that you can in case you anticipate integrating other services beyond fern, you can collect the KYC data once from your customer and submit it to multiple providers. We also enable you to submit or to collect KYC and KYB data from your customers via a hosted form. And this is where the organization branding that you provide to us, such as your name and logo, your organization or project name and logo will be used to make the hosted forms feel a little bit more customized to you and your company. KYC is very fast.

It's usually an automated process unless this is a particularly high-risisk customer. Usually KYC completes in less than 10 minutes versus KYB is a much longer process. It does require manual review. And so we usually see KYB taking at least one business day. So first there's a step of creating the customer.

Then the customer needs to be verified. This is in order to because we're talking about on and off ramps. This is in order to interact with fiat transacting capabilities. Once the customer is approved, they will get access to all of the transactional functions. While the customer is in the process of being approved, you can still register a crypto wallet for that customer.

You can also register a bank account for the customer. And once you have a crypto wallet and a bank account, depending on whether you're interested in doing an on or an off-ramp, one of these accounts will be the source payment account, one will be the destination payment account. So you can use these bank these payment accounts to then create a quote. And once the quote looks good, you can create a transaction. So we'll walk through each of these steps really quickly and what they look like in the API.

To create a customer, you can hit our customers endpoint and the full documentation and API reference is available at docs.forhq.com. And as I mentioned, in order to verify the customer, you can submit the KYC or KYB details via our API endpoints or leverage our hosted form. This is sort of an example of what a hosted form looks like.

If you choose to use the hosted form, you'll see the logo here replaced with your company logo and uh and that's about it. But it gives a little bit more of a customized look for an otherwise off-the-shelf form. These forms can be very painful to build in practice. So we see a lot of teams getting started by using our hosted forms initially and then over time migrating to a more fully customized API based KYC solution. Once the customer has been created, you can start registering payment accounts to the customer.

As we mentioned before, one of the types of payment accounts you can register is a crypto wallet. We support two different types of crypto wallets in the system today. One is a Fern crypto wallet. If you're registering a Fern crypto wallet, what you're actually doing under the hood is creating a new EVM wallet that's provisioned by Fern. So, we sponsor the gas for all the transactions out of this wallet and assigning it.

you're assigning this uh wallet to the customer. If you're setting up an external crypto wallet, this can be if the customer has a non-custodial wallet for their own first-party transactions or as we mentioned before, if they have a third party that they're interested in making crypto payments to, you can register these as external crypto wallets. And this would be um to not necessarily create a new crypto wallet through the fern API, but to connect an existing external crypto wallet to your customers payment accounts. Any of these wallets can be registered as third parties. And again, this is in case uh most commonly we we see the fern crypto wallet is usually just a firstparty assignment.

Um but there it's possible to make firm crypto wallets for third parties under your customer as well. Uh usually this is most applicable to external crypto wallets. And in order to set a payment account as a third party payment account, you just simply share this flag which is default false and just set it to be true. And that's all. Aside from crypto wallets, you can also register bank accounts for as a payment account under your customer.

The different types of bank accounts that we support today are external bank accounts and fern auto fiat accounts. You'll also see a third type of bank account or fiat account in our API which is called a fern fiat account. We're not covering that in this workshop, but if you're interested in that, you can poke around the docs and learn more. For external bank accounts, this is the most common type of account that we see used. This is usually um you know this will be necessary if you're interested in initiating a first party on-ramp or a first-party off-ramp or also a thirdparty um off-ramp as well or a third party on-ramp as well.

Basically, anytime there's going to be a fiat transaction, you will need to register an external bank account. Um and again, just like with the KYC forms, we have two ways of submitting this data. You can either submit the bank account details via the API and all of that documentation is available at docs.fernhq.com or you can use what we return um to you which is a hosted payment account form that enables you to collect bank account details for the 50 plus fiat currencies that we support just with one form and your branding details will be used in this form as well will show your company logo.

I believe this would be your company logo and um and your company name or your project name, organization name here as well so that it looks a little bit more customized for you. To generate a bank account form link, you would post to our payment accounts endpoint and all you would need to say is that you're interested in creating an external bank account for this customer. You could tell us if it's a thirdparty bank account or or not and we would return this bank account form link in the response and that you can use that to share with your customer. You can also create a fern auto fiat account. So a fern auto fiat account um today we only support these in um a subset of the fiat currencies that we support broadly today.

I believe it's USD, euros and Mexican pesos. But this enables your customers to receive fiat currency. Today it's again USD, euros and Mexican pesos to your to under your customer's name or it's a dedicated account for your customer. And the incoming fiat is automatically converted to a destination cryptocurrency that you can set. It can be a stable coin, it can be a non-stable coin, it can be sort of whatever you'd like.

But these are autoconverting fiat accounts. That's why we call them fern auto fiat accounts. Common use cases for fern auto fiat accounts include if you are building some sort of um application where you'd like your commonly we see this being used for freelancers or remote workers if you'd like them to be able to receive payment um from abroad and receive it in a local currency. Most commonly we see a lot of interest in USD. Um so work for your customers from anywhere in the world can receive USD into a bank account in their name and then have it automatically converted to crypto that they can then use or you can use in your application for whatever the next step is in your application UX.

We also support firstparty and third party registration for bank accounts as well. So just wanted to call that out here. Um, one thing to note is that a customer does not need to be approved or verified in order for the bank account setup to work. So, you can get started collecting all this information for your customers. We think this enables a nicer user experience so that you can collect all of the setup information from your customer in one go instead of waiting for them to be verified before you can start collecting this payment account information.

Once you have the payment account set up, you can create a quote. The most important thing to to think about in a quote is what's the source and what's the destination. The source includes which is the payment account that the funds will be coming from. What's the currency um that the funds will be denominated in? What is the payment method that the the payment rail that the source currency will be arriving on?

And what's the amount that you're going to be sending for this transaction? The destination is where is the money going to? So what's the destination payment account? Which payment rail should we send the money on? What's the destination payment method?

And which currency would you like us to send? And that's the destination currency. So the example quote that's specified here is an on-ramp transaction where the source is USD. The destination is USDC. The customer is going to be sending USD via AC.

They're going to be sending 100 USD via AC. and they'd like the converted um USDC to be received on Ethereum in this payment account. The other thing to note about quotes is uh the notion of a developer fee. So, one of the great things about Fern is that you can use Fern to earn revenue. And the developer fee is how you specify what you would like to make on the transaction.

Basically with the developer fee um you tell us which type uh how you would like which currency you'd like the developer fee to be charged in. Today we only support developer fees in USD and you can tell us what the amount will be for the developer fee and today these are uh we only support flat fees today. So we don't support percentagebased fees or anything like that. Um and this is the amount that's going to come out of the transaction. Um, so if in this case if the user is sending 100 USD, your developer fee is $545.

The user is going to see $94.55 uh 9 94.55 USDC that will hit their wallet on Ethereum. Now in other tiers that are not the builder tier, we enable a lot of flexibility for this developer fee. Fern charges a fee as well.

So that's one thing to note. Um on the builder tier, the developer fee has to be greater than or equal to whatever ferns fee is. So you can effectively just pass on the fern feat cost or you can make some revenue on top of it. On other tiers, we do enable developers to subsidize the fern fee. So you could make your developer fee zero if you'd like.

Um but on the builder tier, your developer fee must be greater than or equal to Fern's fee. So that's one thing, one constraint to keep in mind when you're building as a builder. For quotes to work for fiat currencies, when either the destination or the source currency is a fiat currency, the customer does need to be approved. Otherwise, the quotes will not comp will not work for crypto swaps and crypto transfers. These do not receive these do not require the customer to be approved.

So you can get started with crypto swaps and bridging right off the bat with Fern. Um, and that should work without uh without having to go through KYC. Once you have a successful quote that has all of the details of the transaction, um, the quotes will also return exchange rates and the fern fee. So, you can see what that looks like. Once you've confirmed that the quote looks good, you can then use the quote ID to create a transaction.

So, a transaction is very simple. You hit the transactions endpoint and all you pass need to pass in is the quote ID. um it needs to be a valid quote but otherwise that's uh that's all we need because all the other information was already specified when you created the quote. Once a transaction has been created in the response you will see a set of transfer instructions and the transfer instructions essentially tell you where to tell your customer to transfer the source funds so that the rest of the transaction can be initiated. Um, if you think about it, if you're doing an on-ramp transaction, you will in the response that we return to you, we'll give you a set of bank account details that you can tell your customer or you can if you have some sort of payment processor integrated.

You can inte you can initiate the USD transfer from your customer's bank account directly to the the destination bank account that we give you, the the transfer bank account that we give you. um or you can tell your customer to initiate that transfer themselves, but that funds movement needs to occur before the rest of the transaction can proceed. Uh and same thing with a an off-ramp transaction where you will need to find some way to transfer your customer's crypto funds to the transfer wallet address that we give you before the the fiat payout can occur or any of the next steps of the conversion or the transaction can occur. If the um source payment account is a fern wallet, then the source transfer or a fern account generally speaking, whether it's a fiat account or a fern crypto wallet, the source um the transfer of the source funds will happen automatically. You or your customer do not need to initiate anything and that's because Fern has the ability to initiate the transfer of those funds out of those accounts with your approval.

So transfer instructions are very important to pay attention to. Um, and it's also important to note that just like with quotes, transactions do require customers to be approved before they can um, interact with any fiat currency. If you're only doing a crypto swap or transfer or bridging transaction, these do not require a KYC approval. Okay, so that's sort of an overview of what you can do with burn, how to get started, some of the core API concepts, and how you can use these APIs in practice. As you get started, we're sure that you're going to have tons of questions and we want to support you at the best that we can.

So, there's a few ways that you can get help. The first and by far the best way we think especially for those on the builder tier will be to join our Discord community. Uh this is you can access uh the the server at discord.gg/fernhq. We have a help channel.

Um it's newly freshly minted. So um you'll see it's pretty blank at the moment but in this in the screenshot um but you can use the help channel to ask your questions um help other builders who are also integrating the fern APIs. And if you and our team is monitoring these channels so we're also in there answering questions for you. But if you want to make sure that something gets created as a ticket on our system, you can use the Discord emo uh sorry, the ticket emoji to react to your your own post and that would create a ticket in our customer support system to make sure that it's something we're tracking if you haven't gotten a response yet and we can um we can make sure to respond to you as quickly as possible. So, Discord is going to be probably the best way for builders to start getting help as quickly as possible.

Um, and we also have within the developer dashboard a support um, interface as well. So you can use the chat interface um, in order to ask our AI chatbot your questions and see if it gives you a legitimate response. We also have some knowledgebased articles that you can use to answer um, commonly asked questions. And if neither of those works for you, you can also just start a new chat. And similarly to how our ticketing system works, this will create a new ticket for us and we will get to it as soon as we can and make sure that we answer your questions.

And I believe that's it. So it's sort of an overview of how Fern works. Um we believe that money should move like magic and we want to empower you to build the most beautiful, seamless, powerful user experiences using the Fern APIs. Um, we'd love to hear from you in whether it's in our Discord community and asking for help or just sharing a little bit more about what you're building. We love seeing what people build with Fern.

Um, we also love spotlighting builders um who are building really interesting things. So, yeah, would love for you to reach out, stay in touch, ask us any questions, find ways to collaborate with our team. We're just really excited to see what you build and we're here to support you. Thank you. [Music]