convez.ai
MCP ServerIntegração & APIsAvançado
wh0amibjm

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 GitHub
InicialPluginScore · de 0 a 100

SDK 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-sdk

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 2 meses
Versão
v0.7.0
Issues abertas
0
Contribuidores
1

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…UseWhat it addsNeeds
an MCP-capable agent / host (Claude Desktop, Cursor, …)the MCP server (cmd/brainapi-mcp)typed tools, read-only by default, structured errors — no shellthe brainapi-mcp binary
building on Claude Code specificallythe Agent Skill (clients/skill)the CLI surface + judgment / safety railsthe brainapi binary, jq, a shell
scripting from Node / Python / shellthe CLI as a subprocess (see docs/sdk-protocol.md)stable JSON envelope + exit codes, any languagethe brainapi binary
embedding in a Go programthe library (pkg/brainapi)typed methods, full controlGo 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.

EndpointLibrary methodCLI commandExample
POST /authenticationClient.Loginauth login201 normal / persona / 401 invalid
GET /authenticationClient.Probeauth probesecondary / 401 no-creds
DELETE /authenticationClient.Logoutauth logout(204, no body)
POST /authentication/personaClient.CompletePersona(dead-code safety net)—
GET /alphas/{id}Client.GetAlphaalphas getalpha
GET /alphas/{id}/checkClient.CheckAlphaalphas checkterminal
POST + GET /alphas/{id}/submitClient.SubmitAlphaalphas submit200 pending / 403 corr-fail
GET /alphas/{id}/recordsets/pnlClient.AlphaPnLalphas pnlpnl
GET /competitions/{cid}/alphas/{id}/before-and-after-performanceClient.BeforeAndAfterPerformancealphas performance --competition <cid>perf
GET /users/self/alphasClient.ListAlphas / ListAlphasAllalphas list [--status] [--filter] [--all]page
POST /simulationsClient.CreateSimulationsimulations create(returns 201 with Location header only)
GET /simulations/{id}Client.GetSimulation / WaitForSimulationsimulations get / waitin-progress / complete
GET /users/selfClient.Selfusers selfself
GET /users/self/competitionsClient.Competitionsusers competitionscompetitions
GET /users/self/activities/{kind}Client.Activities + DecodeActivitiesusers activitiessimulations (DAILY) / other-payment empty (LIST)
GET /users/self/messagesClient.Messages / MessagesAllmessages list [--all]page
GET /operatorsClient.Operatorsschema operatorsoperators
GET /data-fieldsClient.DataFields / DataFieldsAllschema data-fields [--all]page
POST /usersClient.Registerregister(register success path varies — see captcha leg)
POST /user/email/reverifyClient.ReverifyEmailemail reverify(2xx status, body shape unstable)
POST /user/email/verifyClient.VerifyEmailemail verify(2xx status, body shape unstable)
POST /user/password/forgotClient.ForgotPasswordpassword forgot(2xx status, body shape unstable)
POST /user/password/resetClient.ResetPasswordpassword reset(2xx status, body shape unstable)
GET /captchaClient.FetchCaptchaChallenge(used internally by Register)challenge

Generic error-envelope examples: DRF 400 for kind=drf_validation shape.

Configuration

FlagEnvDefaultNotes
--base-urlBRAINAPI_BASE_URLhttps://api.worldquantbrain.comOverride for staging / proxy
--userBRAINAPI_USER(none)Required for auth and any endpoint behind login
--passBRAINAPI_PASS(none)Auto-relogin needs this cached on the Client
--profile(none)chrome131TLS impersonation; auto:<email> rotates by hash
--proxyBRAINAPI_PROXY(none)http://, https://, or socks5://
--cookie-jar(none)${UserCacheDir}/brainapi/cookies-<email>.jsonFile-backed jar with atomic save
--timeout(none)15sPer-request HTTP timeout
--log-level(none)warnerror|warn|info|debug — log on stderr, JSON on stdout
--output(none)jsonOutput format (only json is currently supported)

Exit codes (CLI)

Designed for shell pipelines. Every code is stable across SDK releases.

CodeMeaning
0Success
2Usage error (bad flag, missing required arg)
3Rate-limited or cooldown
4Account banned or unverified
5DRF field-validation failure (e.g. registration body missing fields)
6Generic API error (4xx without DRF envelope, or 5xx after retries)
7Daily budget exhausted (in-process gate)
8Network / transport error
10Persona 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-After is a float-second string ("5.0"), not an int. Parsed via strconv.ParseFloat; clamped to [1s, 120s] for 429 and [0.5s, 30s] for 503 long-polls.
  • POST /alphas/{id}/check returns 405 — GET-only, long-polls on 200 + empty body + Retry-After.
  • SELF_CORRELATION verdict only comes from /alphas/{id}/submit long-poll, never from GET /alphas/{id} (which stays result: "PENDING" indefinitely for unsubmitted alphas).
  • GET /alphas/{id}/correlations/self is the pre-submit corr gate and signals "still computing" two ways depending on account tier: 503 + Retry-After (Conditional-Consultant) or 200 + empty body + Retry-After (TUTORIAL). The SDK opts into both longPoll503 and longPoll200Empty so the transport retries either signal — without this dual path, fresh-alpha first calls misleadingly return long_poll_exceeded. Gate SubmitAlpha on *block.Max < 0.7 (same threshold BRAIN's post-submit SELF_CORRELATION check uses) to avoid wasting daily submit slots on guaranteed-fail submissions.
  • POST /alphas/{id}/submit returns 503 for the acceptance, not the failure — the SDK treats it as "queued" and proceeds to GET-poll.
  • POST /alphas/{id}/submit on an already in-flight submission returns a 303 back to the same URL (BRAIN's "still processing, poll again" signal) whose Location carries an http:// 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 429 with body {"detail":"THROTTLED"} means BRAIN's submission/correlation subsystem is hung — in-flight SELF_CORRELATION never 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 the rate_limit error's details.body, so callers can tell "platform is down, retry later" from a per-request cap.
  • GET /operators returns a bare JSON array; GET /data-fields uses {count, results} (no next/previous); GET /users/self/alphas uses the full Django REST envelope. Three different shapes — handled per endpoint.
  • Activity records.records are positional tuples, not dicts. Use DecodeActivities to convert via the schema.properties column map.
  • Persona inquiry envelope at login ({"inquiry":"..."}) is operationally dead-code in current BRAIN production, but kept as a safety net (see docs/protocol.md).
  • Altcha PoW captcha is mandatory for POST /users. SDK fetches /captcha, parallel-solves SHA-256 brute-force across runtime.NumCPU() workers (typically <60ms), and injects the base64 payload into auxiliary.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-lint v2 config — errorlint, bodyclose, gocritic, nilerr, unparam, misspell, unconvert on top of the standard set (errcheck, govet, staticcheck, ineffassign, unused) — plus gofumpt -extra formatting.
  • Pre-commit hooks: gofumpt, go vet, golangci-lint, go mod tidy, plus a Conventional-Commits subject check — all run before every commit (the full -race test suite runs in CI and on pre-push).
  • Test coverage: every endpoint method has a unit test driven by httptest.Server replaying real BRAIN-captured payloads from testdata/. Retry-policy tests cover float-Retry-After, ban-after-streak, cooldown, DRF envelope decoding, long-poll cap.
  • Integration tests: gated by BRAINAPI_INTEGRATION=1 env 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.

Ver o original no GitHub

Bom para

Relacionados