WorldQuant BRAIN API Go SDK
wh0amibjm/brainapi-go-sdk
SDK Go tipado e CLI para WorldQuant BRAIN com retry inteligente e solver de captcha
Ver no GitHubSDK tipado em Go + CLI multiplataforma para a API HTTP do WorldQuant BRAIN, plataforma de desenvolvimento de estratégias quantitativas. Oferece biblioteca importável, binário único compilado, suporte a TLS impersonation, solver de captcha e política de retry robusta para produção.
Instalação
npx convez-ai wh0amibjm/brainapi-go-sdk1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integração programática com plataforma WorldQuant BRAIN via Go
- Automação de submissão e backtesting de alphas quantitativas
- Scripts cross-platform para gerenciamento de portfólio de estratégias
Veredito

SDK bem-arquitetado com atenção a detalhes operacionais (retry policy, TLS impersonation, solver de PoW). Útil para traders e quants que trabalham com WorldQuant BRAIN, mas nicho específico — não é ferramenta genérica.
README
A tradução para o português deste README ainda está na fila.
brainapi-go-sdk
A typed Go SDK + cross-platform CLI for the WorldQuant BRAIN HTTP API.
- Single-binary CLI with stable JSON-in / JSON-out, scriptable from any language
- Importable library (
pkg/brainapi) for embedding in other Go programs - TLS impersonation via
bogdanfinn/tls-client(Chrome 131 default; Safari / Firefox profiles available) - Altcha PoW captcha solver for
POST /users(parallel SHA-256, runtime.NumCPU workers) - Production-grade retry policy: float-parsed
Retry-After, 401 auto-relogin, 403 ban-detection, 503 long-poll for submit/simulations, cooldown on concurrent-sim hints - No CGO, builds for
linux/{amd64,arm64},windows/amd64,darwin/{amd64,arm64}from a single source tree
Install
Prerequisites: a WorldQuant BRAIN
account (the register command can create one) for anything behind login, and —
to build from source — Go 1.26.1+ (check with go version). Neither is needed if
you grab a pre-built binary (below).
# Library
go get github.com/wh0amibjm/brainapi-go-sdk/pkg/brainapi
# CLI (Go 1.26+)
go install github.com/wh0amibjm/brainapi-go-sdk/cmd/brainapi@latest
Or download a pre-built binary (with SHA256SUMS.txt) for your platform from the
Releases page. To build
locally instead, run make release — the binaries land in bin/.
CLI quick-start
# Set credentials once (or pass --user / --pass per command)
export BRAINAPI_USER=me@example.com
export BRAINAPI_PASS=hunter2
# Probe the live session (auto-logs in on 401)
brainapi auth probe
# Fetch an alpha
brainapi alphas get qMPjAxnO
# Pre-submit correlation gate (free of submit-budget cost; threshold 0.7)
brainapi alphas corr qMPjAxnO | jq '.data.max'
# Submit and wait for verdict (long-polls until terminal)
brainapi alphas submit qMPjAxnO | jq .data
# Enumerate the operator catalog
brainapi schema operators | jq 'length'
# Tier-required data-fields query (4 params are mandatory)
brainapi schema data-fields --region USA --universe TOP3000 --delay 1
# Drain every active alpha across all pages
brainapi alphas list --status ACTIVE --all | jq '.data.count'
# Filter by value — operator embedded in the field, repeatable (AND)
brainapi alphas list --status UNSUBMITTED --filter 'is.fitness>=3' --filter 'is.turnover<=0.7' --all | jq '.data.count'
# Get yesterday's submit count
brainapi users activities submissions --decode | jq '.data.yesterday.value'
Library quick-start
package main
import (
"context"
"fmt"
"log"
"runtime"
"github.com/wh0amibjm/brainapi-go-sdk/pkg/brainapi"
"github.com/wh0amibjm/brainapi-go-sdk/pkg/captcha/altcha"
)
func main() {
cl, err := brainapi.NewClient(brainapi.Options{
Email: "me@example.com",
Password: "hunter2",
Profile: brainapi.ProfileChrome131,
CookieJarPath: "data/cookies.json",
CaptchaSolver: altcha.CaptchaAdapter{Workers: runtime.NumCPU()},
})
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
info, err := cl.Probe(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Printf("logged in as %s (%v)\n", info.User.ID, info.Permissions)
}
Runnable examples live in examples/ — e.g. go run ./examples/list_active,
plus the corr-then-submit gate (corr_then_submit) and account registration
(register_one, which creates a real account). Set BRAINAPI_USER / BRAINAPI_PASS first.
Integrating from another language
If you're calling brainapi as a subprocess from Node / Python / shell rather
than embedding pkg/brainapi in a Go program, read
docs/sdk-protocol.md first. It defines the
stable JSON envelope, the exit-code → error.kind map, the stdin / --decode
conventions, and the non-obvious schema traps (activities.current is
month-to-date not today; BRAIN day rolls at 3 AM ET; etc.).
The bundled TypeScript client under clients/typescript/ is
the reference wrapper — see its envelope parser, typed-exception hierarchy, and dependency-free subprocess (child_process.spawn) plumbing.
MCP server
For AI agents, cmd/brainapi-mcp exposes the same SDK as an MCP
server over stdio — no subprocess-per-call, it embeds pkg/brainapi directly.
go install github.com/wh0amibjm/brainapi-go-sdk/cmd/brainapi-mcp@latest
# or build locally: make build-mcp → bin/brainapi-mcp
(or grab the pre-built brainapi-mcp-<version>-<os>-<arch> from the
Releases page.)
Register it with any MCP client using the standard config block. Credentials go in
the env block (the server reads BRAINAPI_USER / BRAINAPI_PASS); all logs go to
stderr, so stdout stays pure JSON-RPC:
{
"mcpServers": {
"brainapi": {
"command": "/path/to/brainapi-mcp",
"args": [],
"env": {
"BRAINAPI_USER": "me@example.com",
"BRAINAPI_PASS": "hunter2"
}
}
}
}
Read-only by default. The server registers 20 read-only (GET) tools
(probe, whoami, operators, get_alpha, check_alpha, self_correlation,
alpha_pnl, list_alphas, data_fields, get_simulation, … ) plus
report_issue — an always-on agent feedback channel for reporting defects in the
SDK itself (independent of --enable-writes; gated by confirm=true, and without
a token it just returns a click-to-file draft URL) — so the default surface is
21 tools. The 10 mutating tools (submit_alpha, simulations_create,
register, login, logout, email_verify, email_reverify,
password_forgot, password_reset, persona_complete) are registered only
when you pass --enable-writes in args (31 tools total). submit_alpha is
doubly gated even then: it runs the self-correlation gate (max < 0.7) first and
requires confirm=true, otherwise it returns a dry-run and spends no daily slot.
On error, every tool returns an isError result whose content is a structured
{kind, message, details} JSON payload — the same stable error taxonomy the CLI
exposes (rate_limit, budget, banned, drf_validation, …) — so an agent can
branch on kind instead of parsing the message. Write tools that take a request
body (simulations_create, register) accept it as a typed object with a real
input schema, not an opaque JSON string.
Agent Skill
For Claude Code and other Claude-family
agents, an installable Agent Skill wraps the CLI with judgment and safety
rails (discovery-first via describe, exit-code branching, and a
correlation-gated safe-submit helper). One-command install:
make install-skill # installs into ~/.claude/skills
# or, standalone: bash clients/skill/install.sh
See clients/skill/ for the SKILL.md and what it adds on top of
the raw CLI.
Which integration should I use?
| You are… | Use | What it adds | Needs |
|---|---|---|---|
| an MCP-capable agent / host (Claude Desktop, Cursor, …) | the MCP server (cmd/brainapi-mcp) | typed tools, read-only by default, structured errors — no shell | the brainapi-mcp binary |
| building on Claude Code specifically | the Agent Skill (clients/skill) | the CLI surface + judgment / safety rails | the brainapi binary, jq, a shell |
| scripting from Node / Python / shell | the CLI as a subprocess (see docs/sdk-protocol.md) | stable JSON envelope + exit codes, any language | the brainapi binary |
| embedding in a Go program | the library (pkg/brainapi) | typed methods, full control | Go 1.26.1+ |
Endpoint coverage
Every documented BRAIN endpoint is wrapped 1:1 as both a library method and a CLI subcommand. The Example column links to the canonical response fixture in testdata/ — wrappers can use these to bootstrap typed models without reading Go source.
| Endpoint | Library method | CLI command | Example |
|---|---|---|---|
POST /authentication | Client.Login | auth login | 201 normal / persona / 401 invalid |
GET /authentication | Client.Probe | auth probe | secondary / 401 no-creds |
DELETE /authentication | Client.Logout | auth logout | (204, no body) |
POST /authentication/persona | Client.CompletePersona | (dead-code safety net) | — |
GET /alphas/{id} | Client.GetAlpha | alphas get | alpha |
GET /alphas/{id}/check | Client.CheckAlpha | alphas check | terminal |
POST + GET /alphas/{id}/submit | Client.SubmitAlpha | alphas submit | 200 pending / 403 corr-fail |
GET /alphas/{id}/recordsets/pnl | Client.AlphaPnL | alphas pnl | pnl |
GET /competitions/{cid}/alphas/{id}/before-and-after-performance | Client.BeforeAndAfterPerformance | alphas performance --competition <cid> | perf |
GET /users/self/alphas | Client.ListAlphas / ListAlphasAll | alphas list [--status] [--filter] [--all] | page |
POST /simulations | Client.CreateSimulation | simulations create | (returns 201 with Location header only) |
GET /simulations/{id} | Client.GetSimulation / WaitForSimulation | simulations get / wait | in-progress / complete |
GET /users/self | Client.Self | users self | self |
GET /users/self/competitions | Client.Competitions | users competitions | competitions |
GET /users/self/activities/{kind} | Client.Activities + DecodeActivities | users activities | simulations (DAILY) / other-payment empty (LIST) |
GET /users/self/messages | Client.Messages / MessagesAll | messages list [--all] | page |
GET /operators | Client.Operators | schema operators | operators |
GET /data-fields | Client.DataFields / DataFieldsAll | schema data-fields [--all] | page |
POST /users | Client.Register | register | (register success path varies — see captcha leg) |
POST /user/email/reverify | Client.ReverifyEmail | email reverify | (2xx status, body shape unstable) |
POST /user/email/verify | Client.VerifyEmail | email verify | (2xx status, body shape unstable) |
POST /user/password/forgot | Client.ForgotPassword | password forgot | (2xx status, body shape unstable) |
POST /user/password/reset | Client.ResetPassword | password reset | (2xx status, body shape unstable) |
GET /captcha | Client.FetchCaptchaChallenge | (used internally by Register) | challenge |
Generic error-envelope examples: DRF 400 for kind=drf_validation shape.
Configuration
| Flag | Env | Default | Notes |
|---|---|---|---|
--base-url | BRAINAPI_BASE_URL | https://api.worldquantbrain.com | Override for staging / proxy |
--user | BRAINAPI_USER | (none) | Required for auth and any endpoint behind login |
--pass | BRAINAPI_PASS | (none) | Auto-relogin needs this cached on the Client |
--profile | (none) | chrome131 | TLS impersonation; auto:<email> rotates by hash |
--proxy | BRAINAPI_PROXY | (none) | http://, https://, or socks5:// |
--cookie-jar | (none) | ${UserCacheDir}/brainapi/cookies-<email>.json | File-backed jar with atomic save |
--timeout | (none) | 15s | Per-request HTTP timeout |
--log-level | (none) | warn | error|warn|info|debug — log on stderr, JSON on stdout |
--output | (none) | json | Output format (only json is currently supported) |
Exit codes (CLI)
Designed for shell pipelines. Every code is stable across SDK releases.
| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Usage error (bad flag, missing required arg) |
| 3 | Rate-limited or cooldown |
| 4 | Account banned or unverified |
| 5 | DRF field-validation failure (e.g. registration body missing fields) |
| 6 | Generic API error (4xx without DRF envelope, or 5xx after retries) |
| 7 | Daily budget exhausted (in-process gate) |
| 8 | Network / transport error |
| 10 | Persona 2FA inquiry envelope returned by login (rare; dead-code in current BRAIN production) |
BRAIN protocol gotchas (mirrored in code)
These caveats — captured by Chrome DevTools auditing against platform.worldquantbrain.com — are baked into the SDK so callers never have to think about them:
Retry-Afteris a float-second string ("5.0"), not an int. Parsed viastrconv.ParseFloat; clamped to[1s, 120s]for 429 and[0.5s, 30s]for 503 long-polls.POST /alphas/{id}/checkreturns 405 — GET-only, long-polls on 200 + empty body + Retry-After.- SELF_CORRELATION verdict only comes from
/alphas/{id}/submitlong-poll, never fromGET /alphas/{id}(which staysresult: "PENDING"indefinitely for unsubmitted alphas). GET /alphas/{id}/correlations/selfis the pre-submit corr gate and signals "still computing" two ways depending on account tier:503 + Retry-After(Conditional-Consultant) or200 + empty body + Retry-After(TUTORIAL). The SDK opts into bothlongPoll503andlongPoll200Emptyso the transport retries either signal — without this dual path, fresh-alpha first calls misleadingly returnlong_poll_exceeded. GateSubmitAlphaon*block.Max < 0.7(same threshold BRAIN's post-submitSELF_CORRELATIONcheck uses) to avoid wasting daily submit slots on guaranteed-fail submissions.POST /alphas/{id}/submitreturns 503 for the acceptance, not the failure — the SDK treats it as "queued" and proceeds to GET-poll.POST /alphas/{id}/submiton an already in-flight submission returns a303back to the same URL (BRAIN's "still processing, poll again" signal) whoseLocationcarries anhttp://scheme (+:443) the HTTP/2 transport rejects (http2: unsupported scheme). The SDK disables redirect-following and treats the 3xx as a keep-polling tick, so re-submits / poll-resumes don't crash.- A
429with body{"detail":"THROTTLED"}means BRAIN's submission/correlation subsystem is hung — in-flightSELF_CORRELATIONnever completes, so the ~3 concurrent slots never free and every submit 429s — distinct from a routine rate limit. The SDK surfaces the 429 body under therate_limiterror'sdetails.body, so callers can tell "platform is down, retry later" from a per-request cap. GET /operatorsreturns a bare JSON array;GET /data-fieldsuses{count, results}(no next/previous);GET /users/self/alphasuses the full Django REST envelope. Three different shapes — handled per endpoint.- Activity
records.recordsare positional tuples, not dicts. UseDecodeActivitiesto convert via theschema.propertiescolumn map. - Persona inquiry envelope at login (
{"inquiry":"..."}) is operationally dead-code in current BRAIN production, but kept as a safety net (seedocs/protocol.md). - Altcha PoW captcha is mandatory for
POST /users. SDK fetches/captcha, parallel-solves SHA-256 brute-force acrossruntime.NumCPU()workers (typically <60ms), and injects the base64 payload intoauxiliary.captcha. - BRAIN day rolls at 3 AM US/Eastern, not midnight. In-process daily-budget counter is keyed accordingly.
- 403 ban detection counts consecutive 403s after a re-login attempt. Disable the gate by setting
BanThreshold: 0.
Build
make all # lint, test, build both binaries (CLI + MCP) for the current platform
make release # cross-compile both binaries for all five (linux x{amd64,arm64}, windows amd64, darwin x{amd64,arm64})
make cover # coverage report
make install-hooks # git pre-commit via .githooks/
pre-commit run --all-files # equivalent, using the pre-commit framework
make build / make build-mcp need only the Go toolchain. make all, make lint, make fmt, and the commit hooks additionally require these dev tools:
go install mvdan.cc/gofumpt@latest # formatter
# golangci-lint v2.x — see https://golangci-lint.run/welcome/install/
pip install pre-commit # or: uvx pre-commit # hook runner
make vuln needs nothing extra — it runs govulncheck via go run.
Single-source-tree, no CGO, no platform-specific build tags — the same
./cmd/brainapi package compiles cleanly for every target.
Engineering standards
- Lint: a curated
golangci-lintv2 config —errorlint,bodyclose,gocritic,nilerr,unparam,misspell,unconverton top of the standard set (errcheck,govet,staticcheck,ineffassign,unused) — plusgofumpt -extraformatting. - Pre-commit hooks:
gofumpt,go vet,golangci-lint,go mod tidy, plus a Conventional-Commits subject check — all run before every commit (the full-racetest suite runs in CI and onpre-push). - Test coverage: every endpoint method has a unit test driven by
httptest.Serverreplaying real BRAIN-captured payloads fromtestdata/. Retry-policy tests cover float-Retry-After, ban-after-streak, cooldown, DRF envelope decoding, long-poll cap. - Integration tests: gated by
BRAINAPI_INTEGRATION=1env so CI doesn't accidentally hit production.
Protocol truth
The endpoint shapes encoded in pkg/brainapi/types.go mirror the Chrome-DevTools-verified response captures pinned under testdata/ and documented in docs/protocol.md. When BRAIN's protocol changes, re-capture the live shape, update the fixture and protocol notes, then port the change into the typed structs.
Contributing
Issues and PRs are welcome. See CONTRIBUTING.md for the
protocol contract, the pre-commit gate, and test expectations;
SECURITY.md for how to report a vulnerability; and
CHANGELOG.md for release history.
Disclaimer
This is an unofficial, community-built client and is not affiliated with, endorsed by, or sponsored by WorldQuant. "WorldQuant" and "BRAIN" are trademarks of their respective owners and are used here only to describe the API this SDK talks to. Use it in accordance with the platform's Terms of Service; you are responsible for how you use your own account. The software is provided "as is", without warranty of any kind (see LICENSE).
License
MIT — see LICENSE.