Prove your dev skills with Folks Finance in Algorand’s Build-A-Bull Hackathon

Folks Finance
6 min readOct 9, 2023

Hey Algorand devs, Folks Finance is joining the upcoming Algorand Build-A-Bull Hackathon taking place in October! In partnership with the Algorand Foundation, the Folks team has defined a prize of up to $10,000 for you.

The proposed challenge will be to develop a UI for the Folks Router Widget, the new DEX aggregator built by the Folks team. By pulling data from three top exchanges on Algorand — Pact, Tinyman, and Humble — Folks Router guarantees the lowest slippage and best prices on swaps. What it needs is a beautifully enticing interface which will allow any project to integrate Folks Router for their own purposes.

That’s where you come in.

Important Dates:

Hacking Window: October 18th — November 15th

Finalists Announced: November 29th

Build-A-Bull Grand Prize Demo Day: December 13th

How to Participate?

1. Visit the Algorand Build-A-Bull Hackathon website to register.

2. Form a team or go solo — the choice is yours.

3. Start hacking on October 18th, and work on your innovative solution until November 15th.

4. Submit your project, and you could be one of the finalists announced on November 29th.

5. Prepare to dazzle the judges and the Algorand community on December 13th during the Grand Prize Demo Day.

We hope you’ll join the fun! If you’re interested, you can find all the details for how to enter the competition below:


Core Features

  1. Wallet connectivity: The widget should allow for the direct connection of a wallet within its interface, using If, on the other hand, a protocol integrating the widget already has its own infrastructure with the wallet, a message exchange must take place in which unsigned transactions are sent to the host site/app, which will take care of signing them. The widget will be also responsible for submitting the signed transactions to the blockchain. Both options should be supported simultaneously, and the choice between the two should be left to the developer using the widget.
  2. API Utilisation: The widget utilises Folks Router’s APIs to fetch swap quotations and related transactions (unsigned).
  3. Themes: The widget should offer both light and dark themes, selectable by the developer using the widget. The basic themes must be in line with the colours of folks finance. It is appreciated if it can be easily customised by the developer using it.
  4. Swap modes:
  • If the user enters a value in the “From” field, the swap will be of the “fixed input” type.
  • Conversely, if a value is entered in the “To” field, the swap will be of the “fixed output” type.
  • The last manually entered value will determine the type of swap to be executed.

5. API Request Debouncing: When the user manually enters a value in either the “From” or “To” input fields, API calls for quotations should be debounced.

6. Automatic Quotation Updates: Every ‘X’ seconds, the widget should re-fetch the quotation to display updated values. Some form of countdown or indicator should communicate when the next refresh will occur or how long the current quotation is considered valid.

7. Asset Selection: The user should be able to choose from a preset list of assets. If the user wants to swap an asset not in the initial list, it must be possible for him to manually enter an asset id. The information of the assets to be displayed are name, icon and amount that the user has in the wallet. If a manually added asset has a recognised icon, it must be displayed.

8. Simulate Swap: Even if the user does not have the wallet connected or does not have enough funds, it must be possible for him to enter arbitrary amounts in the input fields. In this case, the button to swap will be disabled and the reason must be shown in the input form.

9. Invert selected assets: It must be possible to invert the 2 assets currently selected by simply clicking a button (arrow icon for example).

10. Dollar Prices: The dollar value of the assets must be shown, based on the amounts used. It is preferable to use vestige API. It is appreciated if a multi-currency display is supported.

11. Swap Routes: Using an accordion, it has to be possible to display the swap routes.

12. Handle Opt-in: If the connected wallet needs to opt-in, the opt-in transaction must be added to the group to be signed by the user

13. Gas Fee: If the user does not have enough ALGO to pay the fees (net of the min-balance), he should never go so far as to sign the transaction that it will surely fail. Instead, he must be warned with a message explaining that he does not have enough to pay the fees. Possibly also showing the amount of gas fees he will have to pay.


The widget should be compatible with both web and mobile contexts and should not be restricted to applications developed in React. Although most web3 applications are developed in React, all possible technology stacks have to be supported.

Development and technologies

Recommended Technological Approach

The most flexible and scalable approach consists of several steps:

  1. Create a Monorepo: Use Turborepo to create a monorepo. This centralises code management, making it easier to maintain and update the project.
  2. Develop a React Component: Design a React component that encompasses all the necessary functionalities. Publish this component on npm immediately, making it readily available for integration in projects that use React.
  3. Build a webapp: Use either Next.js or a base React application with Vite to create a web application. Deploy this application to a specific URL. This application will simply import and utilise the previously created React component.
  4. Implement a Communication Library: Create a library that facilitates communication between the deployed web application and any host protocols that will use it via iframes or webviews. Utilise the postMessage method to achieve bidirectional communication. Additionally, add communication primitives to the web application to ensure effective two-way communication.

Possible Monorepo Structure

A potential structure for the monorepo could be:

  • /apps/swap-widget-website
  • /packages/swap-widget-react
  • /packages/swap-widget-js

By using this structure, projects that utilise React can effortlessly integrate the published component (/swap-widget-react). Projects that use different technologies (other frameworks or mobile environments) will use the specialised library (/swap-widget-js) for integration.

The most important element of the development that will be given the most importance during evaluation is /packages/swap-widget-react.

This approach is designed to easily accommodate changes and new features, making it highly scalable.

The above architecture is a guideline with easy expandability, scalability and easy maintenance as its main objective. A different approach is possible, but subject to approval.

In addition, a basic design is provided to be used as a starting point for development. Any improvements in terms of UX and comprehensibility are welcome.

The end result that will be evaluated must be a PR to the repository at this link Folks-Finance/folks-router: Enable the most efficient swaps on Algorand (

We’re looking for a high quality solution. The bounty can be as high as $10,000. Folks Finance reserves judgment to award a lower amount if some of the previously listed requirements are unfulfilled or we believe the UI is lacking.

Chat with our technical team in the official developer discord channel and visit the Folks Router website for the documentation and other important details!

Innovation starts with you!

About Folks Finance:
Folks Finance is a leading DeFi platform providing innovative tools for lending, borrowing, trading and managing digital assets, all in one place. Folks Finance streamlines the DeFi experience with a UI and UX competitive to centralized exchanges, all while running on permissionless smart contract technology.



Folks Finance

DeFi at its finest: lend, borrow, trade, and manage digital assets all in one place.