Overview
PolarisLink has two reference client libraries. Both implement the same wire contract described in the specification, both are released under the Apache License 2.0, and both live in the PolarisLink repository. They follow the protocol version in lockstep, so client 2.6.1 matches protocol 2.6.1.
| Python client | C++20 client | |
|---|---|---|
| Location in the repository | python/ |
cpp/ |
| Form | Package named polarislink |
Single header polarislink/polarislink.hpp |
| Dependencies | None required; pandas is optional | libcurl when available; no other mandatory third-party code |
| Language level | Python 3.9 or later | C++20 |
| Command line | polarislink command |
None |
| Credentials | FORTICIA_API_KEY or a constructor argument |
FORTICIA_API_KEY or a constructor argument |
| Gateway address | FORTICIA_API_URL or a constructor argument |
FORTICIA_API_URL or a constructor argument |
For installation and a first call in each language, follow the quickstart.
Python client
The Python client is built on the standard library alone, so it installs cleanly into any environment, including restricted ones. When pandas is present, bar queries can return a data frame.
The class is PolarisLinkClient, with ForticiaClient and PolarisLink as aliases. Every method maps to one route in the specification and returns parsed JSON, a list, or text for Markdown routes.
What it covers
| Area | Examples |
|---|---|
| Telemetry and governance | get_telemetry, get_knowledge, sync_governance, get_spec, get_changelog |
| Runs | log_run, get_runs |
| Event stream | stream_polaris_events |
| Issues | report_issue, list_issues, get_issue, add_issue_comment, update_issue, attachment upload and download |
| Workspaces, tasks and drive | list_workspaces, get_tasks, create_task, update_task, get_drive_files, upload_drive_file |
| Activity and notifications | get_activity, log_activity, get_notifications, update_notifications |
| Coordination plane | Leases (claim_swarm_lease, release_swarm_lease), heartbeats, negative results, assistance requests, cross-audit, patrol notices, deliberations, stream_swarm_events |
| Compute delegation | dispatch_compute_job, get_compute_job, get_compute_capacity, cancel_compute_job |
| Research ledger | export_research_log |
| Market-data example module | get_universes, get_bars, get_options_surface, get_options_history, download_dataset |
Command-line interface
Installing the package adds the polarislink command. Global options such as --key and --url go before the sub-command. The polaris group covers the core protocol: telemetry, knowledge, runs, log-run, stream, work, add-task, issues, get-issue, report-issue, comment-issue and update-issue. The swarm group covers the coordination plane.
Tests and compatibility
The repository runs the Python tests on Python 3.9, 3.10, 3.11 and 3.12 in continuous integration.
C++20 client
The C++ client is a single header intended for engines and services that cannot take on a heavy dependency tree. It exposes a polarislink::Client class with plain structures for the data it returns.
Transport
The client has two transports and chooses at compile time.
- With libcurl present, requests run in process, with no subprocess and no credentials in an argument list.
- Without libcurl, a fallback transport passes configuration through standard input or a file readable only by its owner, so the key never appears in a process listing.
Define POLARISLINK_NO_LIBCURL to force the fallback.
What it covers
| Area | Examples |
|---|---|
| Telemetry and governance | get_telemetry, get_knowledge |
| Runs | log_run with a BacktestRunMetrics structure; numeric fields are optional values |
| Issues | report_issue |
| Coordination plane | Lease claim and release, heartbeats, negative-result broadcast, cluster status |
| Notifications | Read and update preferences |
| Market-data example module | get_bars, get_options_surface, get_options_history into native structures |
Build and tests
The repository builds the header with Clang and runs its tests with CTest in continuous integration. Add it to a CMake project with add_subdirectory(cpp) and link the polarislink::polarislink target.
Security notes
- Keys belong in the environment or a secret store, not in source files or in command lines.
- Use a key with the narrowest scope that does the job. A workspace-bound key can file and comment on issues in one workspace and nothing else.
- Treat the response of a gateway as untrusted input in your own code, as you would any network data.
Where to go next
- Quickstart: install, authenticate and make a first call.
- Specification: the wire contract the clients implement.
- Changelog: what changed in each release.
- Source and issues on GitHub.
Get started
The protocol and the clients are open. The hosted Forticia gateway needs an approved key.