Skip to content

Authentication

All authenticated API endpoints use an HttpOnly session cookie, issued after you sign a bootstrap message with your Solana wallet. There is no API-key header for auth — a per-user api_key is returned, but it is only a builder-attribution token, not a primary auth credential.

Establish a session — POST /v1/builders/register

Request body (BuilderRegistration):

{
  "user": "<base58 Solana pubkey>",
  "name": "session:AbCd1234",
  "signature": "<hex Ed25519 signature>",
  "timestamp": 1750700000
}

Message you must sign (exact, newline-delimited — no trailing newline):

Parti Session
User: {user}
Timestamp: {timestamp}
  • timestamp is unix seconds and must be within 60 seconds of server time, else 400 { "error": "stale_timestamp" }.
  • signature is the 64-byte Ed25519 signature over the UTF-8 bytes of the message above, hex-encoded.

Success: 200 with body { "api_key": "<hex>" } and a Set-Cookie:

parti_oracle_session=<value>; Path=/; Secure; HttpOnly; SameSite=None; Expires=<+7d>
  • Cookie name parti_oracle_session, TTL 7 days, SameSite=None + Secure. A browser client must send credentials: 'include' on every request; a programmatic client must store and replay the cookie.
  • Re-registering returns the same api_key. You may forward it as builder_api_key on order submissions for builder-rebate attribution (default fee_bps = 0).

Side effects on register: auto-provisions a users row (so balance reads work before first deposit) and upserts a builders row. DB failures here do not block sign-in.

  • POST /v1/withdraw-signed — requires a valid session and the session user must equal the body user (403 session_user_mismatch otherwise).
  • POST /v1/orders and order cancel/management — session-scoped; per-wallet rate limiting keys off session.user.
  • The LP-bot endpoints do not rely on the cookie for authorization — they authorize via the user's per-call Ed25519 signature over canonical messages (see LP → LP bot). They still return 403 lp_disabled when LP is not currently open.

Network-domain tags (replay protection)

Cross-chain signed messages (withdraw + LP delegation) prepend a leading ASCII network tag that binds the signature to one network/env — a signature minted on testnet can never be replayed on mainnet:

Env Tag (ASCII, 18 bytes)
testnet / staging parti-fogo-testnet
mainnet / production parti-fogo-mainnet

Production uses Fogo mainnet; non-production uses testnet. Production (oracle-api.parti.com) is mainnet, so sign against the mainnet tag. See LP → Withdrawals for the exact tagged byte layout.

Errors

invalid_json (400), invalid_shape (400), stale_timestamp (400), invalid_signature (403).