SDK overview
Official SDK packages are Planned. No Farbeam package exists on npm, PyPI or any other registry today. If you find a package using the name, it does not come from Farbeam.
The API is plain JSON over HTTPS, so a small client is enough. These guides give you one to copy, with retry and pagination.
| Guide | Runtime | Dependencies |
|---|---|---|
| JavaScript client | Node.js 18 or later, modern browsers | None |
| Python client | Python 3.9 or later | requests |
| Go client | Go 1.21 or later | None |
| Streaming | Browser, Node.js, Python | Node.js and browser none, Python requests |
#What a good client does
Each sample client on the next pages handles the same five things.
| Concern | Rule |
|---|---|
| Base URL | One constant, https://farbeamlabs.com/api/v1 |
| Authentication | Authorization: Bearer <key>, read from an environment variable |
| Errors | Read error.code. Keep error.request_id for reports. |
| Retries | Retry 429 and 502 and network errors. Respect Retry-After. Never retry other 4xx. |
| Pagination | Follow meta.next_cursor as before on /transfers |
You also need to handle the two timestamp types. See versioning.
#Generating a client
The OpenAPI file lists every path, parameter and error status. Tools such as OpenAPI Generator can read it. The file does not hold response schemas today, so generated code returns untyped data for responses. Use the data model for those types.
#Which transport to use
| Need | Use | Cost |
|---|---|---|
| Query recent or past rows, up to 7 days | REST /transfers | 1 unit per page |
| See new rows in a process that stays up | SSE /api/live | No units. 6 streams per network. |
| Get new rows pushed to a server, filtered | Webhooks | No units. Limit of 120 per rule per hour. |
| Read an address or token on demand | REST lookups | 2 to 3 units |
| Check health | REST /status | 0 units |
WebSockets and GraphQL are Planned, and not built.
#Recipes
These recipes combine endpoints into small working programs. Each states its limits.
| Recipe | What it does |
|---|---|
| Exchange flows | Totals labeled exchange transfers by name |
| Token screening | Reads checks for a list of tokens and prints a table |
| Wallet watch | Watches an address with polling and a rule |
| Stablecoin monitor | Tracks supply and large stablecoin moves |
| Status monitoring | Alerts you when a chain poller is not ok |
#Testing your code
Samples in these guides are for your use, and you may change them. They use the live API, and they spend your units. Before you run a loop against the API:
- Read rate limits. A token report costs 3 units.
- Create a key, so you have 120 units per minute and your usage appears on
GET /me. - Add a stop condition to any loop.
#Support
There is no paid support and no SLA. Both are Planned. Questions go to contact@farbeamlabs.com. A good report has the request_id, the UTC time and what you expected.
If you publish your own client, please make clear in its name and README that it is not an official package.