Program & API

This page is the integration reference for binary markets: the on-chain magma_binary_vault program, its PDA seeds, instructions, and account fields; the REST /v1/binary/* surface; and the SDK/program helpers for deriving addresses and building transactions.

On-chain program

Program	Devnet program ID
magma_binary_vault	HLFKqqKXmBfeh43Fiqdj1fBgGuXgpipcNq338Ve1pyd4
magma_crucible_pool	8BqDJTwKAJMSkQzC652N92KvtY7WK9ghqNLfhfru9R2e

Both support SOL and SPL assets. SOL flows use lamport vaults; SPL flows use token vaults (the _tvault / _spl variants).

PDA seeds

All program-derived addresses for magma_binary_vault use the following seeds. Where a seed list includes market_id, that is the 32-byte market identifier (see uuidToMarketId()).

PDA	Seeds	Purpose
Program state	binary_program_state	Global program state / authority
Config	binary_config	Economic parameters (capital_loss_bps, crucible_share_bps, thresholds)
Market state	binary_state, market_id	Per-market state and oracle_status
YES vault (SOL)	yes_vault, market_id	Escrowed YES-side lamports
NO vault (SOL)	no_vault, market_id	Escrowed NO-side lamports
YES vault (SPL)	yes_tvault, market_id	Escrowed YES-side tokens
NO vault (SPL)	no_tvault, market_id	Escrowed NO-side tokens
Backing	binary_back, market_id, backer, side	Per-backer position on one side
Oracle submission	binary_oracle, market_id, oracle	One signer's verdict + confidence
Dispute	binary_dispute, market_id	Dispute record (ML-3)

Because binary_back is keyed by backer and side, a wallet can hold independent YES and NO positions on the same market.

Instructions

Instruction	Asset	Purpose
create_market	SOL	Create a market (Classic or Yield) and initialize its state + vaults
create_market_spl	SPL	Create an SPL-denominated market
back_market	SOL	Back YES or NO with lamports; writes a binary_back position
back_market_spl	SPL	Back YES or NO with tokens
submit_oracle_resolution	—	Oracle signer writes a binary_oracle verdict (vote + confidence)
finalize_resolution	SOL	Permissionlessly finalize once M-of-N + timelock met; unlock payouts
finalize_resolution_spl	SPL	SPL finalization
resolve_dispute	—	Open / resolve a dispute (ML-3); writes binary_dispute
claim	SOL / SPL	Withdraw winnings, the 65% loser return, or a refund
deposit_to_yield	—	Scaffold — CPI to deposit principal into yield (Save/Solend). Not wired into finalize.
withdraw_from_yield	—	Scaffold — CPI to withdraw principal from yield. Not wired into finalize.

Not yet live — yield CPIs

deposit_to_yield / withdraw_from_yield exist on the program but are a scaffold: they are not called from finalize, and total_yield stays 0 at settlement on devnet. The mainnet plan moves principal into Kamino vault positions with realized yield distributed off-chain. See Backing & Settlement.

Key account fields

Account	Notable fields
Config	capital_loss_bps (default 3500), crucible_share_bps (default 5000), oracle threshold, timelock
Market state	market_id, variant (Classic / Yield), source, oracle_status (0/1/3/4), deadline, YES/NO totals, total_yield, finalized
Backing	market_id, backer, side, amount, claimed flag
Oracle submission	oracle pubkey, vote (YES/NO), confidence
Dispute	market_id, disputer, status

oracle_status values: 0 open · 1 resolved (timelock + dispute window) · 3 disputed · 4 refund_triggered. The market is finalized after the timelock with no open dispute.

REST surface

Not yet live — /v1/binary/* returns 503

The entire /v1/binary/* REST surface is scaffolded and gated — every endpoint returns 503 (coming post-TGE). GET /v1/binary/status returns { "feature": "coming_soon" }. Integrate against the on-chain program directly (via the SDK helpers) until these endpoints ship.

Base URL: https://api.magmaprotocol.xyz.

Method	Endpoint	Intended purpose	Status
GET	/v1/binary/status	Feature / availability probe	503 — returns feature: 'coming_soon'
POST	/v1/binary/back	Place a backing	503 — coming post-TGE
GET	/v1/binary/positions/:wallet	A wallet's binary positions	503 — coming post-TGE
GET	/v1/binary/narratives	Binary market listing	503 — coming post-TGE
POST	/v1/binary/withdraw	Withdraw / claim	503 — coming post-TGE

# Today, every /v1/binary/* route is gated:
curl https://api.magmaprotocol.xyz/v1/binary/status
# HTTP/1.1 503 Service Unavailable
# { "feature": "coming_soon" }

Market creation

POST /v1/markets creates a MAGMA-native binary market. It is the programmatic equivalent of the 5-step web flow and is now fee-gated — previously this path was ungated. It carries the same anti-spam gate as narrative /publish: a Cloudflare Turnstile token, the creator wallet's signature, and a verified treasury fee-payment transaction.

Field	Type	Description
cf_token	string	Cloudflare Turnstile token (required) — the human-verification gate.
signature	string	Creator wallet signature over the request.
fee_tx_signature	string	Signature of the confirmed on-chain tx paying BINARY_MARKET_FEE_SOL to the treasury. Verified before creation.
variant	string	classic | yield. Fixed at creation.
question	string	The falsifiable YES/NO question.
deadline	integer	Resolution deadline (unix seconds).
seed_yes / seed_no	number	Optional seed liquidity per side.

The fee defaults to the narrative publish fee: BINARY_MARKET_FEE_SOL falls back to NARRATIVE_PUBLISH_FEE_SOL (~5 SOL — see YBNCM → publish fee).

Reject codes:

Status	Code	Cause
400	TURNSTILE_FAILED	Missing or invalid Cloudflare Turnstile token.
400	market_fee_missing_treasury	No fee-payment tx supplied, or it does not pay the treasury / fails verification.
401	invalid_signature	The creator signature did not verify.

Only native creator markets are fee-gated

The fee applies to MAGMA-native creator markets (seed source). The bot, admin, and classic protocol-created paths run as the protocol's own wallet and are not fee-gated; Kalshi / Polymarket imports keep their own platform gates / KYC and pay no MAGMA fee. See Creating Markets → source types.

SDK & program helpers

Until the REST surface is live, build transactions against magma_binary_vault directly. The SDK (@magma-protocol/sdk) and program tooling expose helpers for the program client, PDA derivation, and market-id conversion.

getBinaryVaultProgram()

Returns an Anchor program client bound to magma_binary_vault (the IDL and program ID HLFKqqKXmBfeh43Fiqdj1fBgGuXgpipcNq338Ve1pyd4). Use it to build and send the instructions above.

const program = getBinaryVaultProgram(/* connection, wallet */);
// program.programId === HLFKqqKXmBfeh43Fiqdj1fBgGuXgpipcNq338Ve1pyd4

PDA derivation

Derive any binary PDA from its seeds. For example, a market's state and side vaults:

const [marketState] = PublicKey.findProgramAddressSync(
  [Buffer.from('binary_state'), marketId],
  program.programId,
);
const [yesVault] = PublicKey.findProgramAddressSync(
  [Buffer.from('yes_vault'), marketId],
  program.programId,
);
const [backing] = PublicKey.findProgramAddressSync(
  [Buffer.from('binary_back'), marketId, backer.toBuffer(), Buffer.from([side])],
  program.programId,
);

uuidToMarketId()

Markets are referenced off-chain by UUID but keyed on-chain by a fixed-width market_id. uuidToMarketId() converts a market UUID into the 32-byte market_id used as a PDA seed:

const marketId = uuidToMarketId('<MARKET_UUID>'); // → 32-byte seed

Use the result anywhere a seed list above includes market_id.

See also

• Overview — variants, lifecycle, program IDs.
• Backing & Settlement — payout math per instruction.
• Mainnet Checklist — what changes before mainnet.