Agent Integration · v0.1

Run an autonomous agent on SupraFX

BFT-consensus settlement infrastructure for cross-chain swaps. The same endpoints the web dApp uses are public and designed for programmatic access — your agent signs locally, posts envelopes, and is a first-class participant on chain.

Pick a path

Three ways to integrate. Same chain, same endpoints, different ergonomics.

Option 1

MCP Server

Claude Desktop · Cursor · Continue

Plug the SDK into any MCP-aware client. Tools appear in the model's palette automatically. Best for human-in-the-loop trading.

Option 2

Direct SDK

Node · TypeScript

Import SupraFxClient + DelegateSigner. Build your own loop. Best for headless market makers and arb bots.

Option 3

Raw REST

Any language

Skip the SDK entirely; sign + POST envelopes. Signing recipe in INTEGRATING-AGENTS.md §4. Best for non-Node stacks.

Authorize a delegate

One-time setup. Your master StarKey wallet authorizes a delegate keypair on chain with per-asset caps and an expiry. The delegate's private key never leaves your machine.

01
Connect StarKey
Open this site, connect your master wallet.
02
Open Profile → Delegates
Right-side panel, top navigation.
03
Click Create Delegate, then Generate
Generates an ed25519 keypair locally and pre-fills the form. The JSON file with the private key downloads ONLY after step 5, when the master signature is committed to chain.
04
Set per-asset caps + expiry
Bound what the delegate can do: max trade size, max cumulative earmark per asset, allowed pairs, expiry batch. Caps must be positive — a value of 0 means 'no trades allowed for this asset' (fail-closed).
05
Sign the policy with StarKey
One signature. The DelegatePolicyCreated event commits to chain in ~1 second. The JSON download triggers AFTER the on-chain commit succeeds — keep it safe, this is the only copy.
06
Pass the JSON to suprafx-mcp init
The wizard prompts for the path; it never sends the key anywhere.

Revoke anytime from the same Delegates tab. Master signs once; every subsequent envelope from the delegate is rejected within ~2 seconds.

Install the MCP server

Three commands. Then SupraFX appears in your AI agent's tool palette.

Install globally

npm install -g @suprafx/agent-sdk

Configure with your delegate key

suprafx-mcp init

The wizard prompts for the JSON file from step 02. Writes ~/.suprafx/config.json mode 0600.

iii

Wire into Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "suprafx": {
      "command": "suprafx-mcp"
    }
  }
}

Restart Claude Desktop. Same JSON shape works for Cursor and Continue.

Resources

OpenAPI 3.1 descriptor→

Machine-readable contract for SupraFX's public HTTP endpoints.

INTEGRATING-AGENTS.md→

Canonical conceptual reference: master/delegate model, settlement modes, asset semantics, error catalog, complete minimal market maker.

@suprafx/agent-sdk on GitHub→

Source of the SDK + MCP server.

Cookbook→

Four runnable examples: passive quoter, inventory-aware quoter, counter-arb taker, and an auto-accept + partial-fills resting taker.

delegate-bot-signing.md→

Focused signing recipe (subset of INTEGRATING-AGENTS.md §4).

Tool reference

12 tools total. 7 always available, 5 unlock when a delegate key is configured.

Read· No signing. Available without a delegate key.

get_chain_info

Chain ID hash + threshold + validator count

get_current_batch

Current committed batch height (chain health probe)

get_sequence_number

Next strict-monotonic seq an address must use

list_assets

All supported assets with chain ID + decimals

get_balances

A master's available + locked balances per asset

get_orderbook

Open RFQs with optional pair / status / taker / since / before / limit filters

get_my_identity

Your delegate address + current sequence number

Write· Requires a configured delegate. Signs + submits envelopes locally.

submit_rfq

Open an RFQ as taker. Locks sell-asset from master balance. Supports auto-accept (pre-commit a target rate → qualifying quotes settle with no accept step) and partial fills (allow_partial_fills + min_fill_size → fill in slices).

place_quote

Quote on an open RFQ as maker. Locks quote-asset.

accept_quote

As taker, pick a maker's quote → settle.

cancel_rfq

As taker, withdraw your open RFQ. Returns locked balance.

withdraw_quote

As maker, pull a pending quote off the book.

Security model

Local key only

Delegate private key stored at ~/.suprafx/config.json (mode 0600). MCP transport is stdio. The key never touches the network.

Bounded on chain

Master's DelegatePolicyCreated sets per-asset caps (0 = no trades for that asset), allowed pairs, expiry. A leaked key cannot exceed these bounds and is auto-expired at the deadline.

Instant revoke

Profile → Delegates → Deactivate. One master signature. Every subsequent envelope from the delegate is rejected within ~2 seconds.

Economics

Two deterministic fees. Model both or your PnL is wrong.

Trade fee

Every settled trade: taker pays 5 bps (0.05%) of the quote notional, maker earns a 1 bp (0.01%) rebate, protocol keeps the 4 bps difference. Netted at settlement — it does not change the on-chain rate. Price quotes to clear your costs plus this.

Withdrawal fee

Withdrawals are currently free — no fee to move funds off the platform to an L1 chain during the test period. (A flat SUPRA fee may return later; it would be enforced on-chain and always paid in SUPRA.)

Auto-accept (taker pre-commit): set auto_accept: true + an auto_accept_target_rate on submit_rfq and the chain settles the first maker quote at or better than that rate automatically — same batch, no accept_quote, taker can be offline. The target is a cryptographic price floor: the chain never fills (or lets anyone accept) a worse quote. Makers — quote at or above an RFQ's target to win it instantly; below is a dead end.

Partial fills: allow_partial_fills: true + min_fill_size let makers fill a slice instead of all-or-nothing; the RFQ stays open with a smaller remaining size until full. Compose with auto-accept for a resting limit order — one large RFQ that auto-settles every qualifying slice at or above your floor, incrementally, taker offline. Manage open orders with cancel_rfq (taker pulls an RFQ, releasing its earmark) and withdraw_quote (maker pulls/reprices a quote). These five write actions are the whole strategy surface — full walkthrough in INTEGRATING-AGENTS.md §6.

Mainnet Beta · cadence ~1 batch/sec · live version = the chain id hash from /api/council/chain-info · open issues on the GitHub repo.