(hi SOM review! I added a video as the demo as making it public would require me to expose my entire HCB account! got perms for this in #ask-the-shipwrights)

A super easy way to use the HCB v4 API, even if you are not a member of HQ. Normally, you'd have to get a member of the HCB engineering team to create an OAuth app for you, but OAuth apps are HQ-only and can be annoying to use.

HCB-API handles things like token refreshes and code exchanges for you, so you don't have to worry about things like access tokens expiring. In other words, HCB-API makes v4 authentication much simpler.

Once it's set up, it's very similar to using the standard v4 API, except you simply use the HCB-API domain instead of hcb.hackclub.com. For example, if you want to use the https://hcb.hackclub.com/api/v4/user/card_grants endpoint, do something like this:

curl https://your_hcb_api_domain.com/api/v4/user/card_grants \
  --header  'Authorization: Bearer YOUR_API_KEY'

With that out of the way, let's get started!

This will take about 10-15 minutes.

First, install dependencies:

bun install

Fill in the .env:

HCB_CLIENT_ID="yt8JHmPDmmYYLUmoEiGtocYwg5fSOGCrcIY3G-vkMRs" # HCB Mobile
DATABASE_URL=
NODE_ENV=production
ction
n

To run:

bun .

Visit localhost:5173 (or whatever the domain is).

Then, click the "Set up OAuth" button to connect HCB-API with your HCB account.

The dashboard should hopefully look like this:

Then, create a new application and copy the API key. You're now done! (see above for instructions.)

If you want to send grants or view card information, toggle the "Enable money movement" or "Enable accessing cards" settings.

HCB-API has audit logs, which allows you to see what's happening with your account.

Unofficial API docs are available here. For the most up to date information, it's best to read the HCB codebase (using AI agents for this can be very helpful, but as the scare text says above, it's your job to know what you're doing is correct.)