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

agent-setup.md (machine-readable runbook)→

Point a coding agent at this and it sets itself up unattended: install, read-only verification, the two operator steps that need a wallet, the cap rule, the lifecycle contract, and the known failure modes with the check that clears each.

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_setup_status

Where you are in setup and the single next step. Call it first.

preflight

Nine checks that decide whether it is safe to trade right now, each with the action that clears it: venue reachable, venue batch actually advancing (not just the L1), assets resolving to registered ids, oracle freshness, custody, sequence drift, funding, and stale own-RFQs still holding collateral.

list_my_open_orders

Every order of yours still holding locked funds — RFQs and quotes — each with the exact call that releases it. The answer to 'where did my money go'.

get_deposit_status

Is a deposit still crediting, credited, or failed? One deposit by chain + tx_hash, or every claim of the master. state is pending | credited | rejected | expired; stale on a pending claim is the fresh-wallet delay (15+ min), NOT a failure — wait and re-read, never re-send. found:false means no claim was recorded; the deposit can still credit, read get_balances.

get_master_address

The master address the server is configured with. Balances and locks live on the master, never on the delegate.

get_oracle_price

Venue fair value for a pair WITH the quote's age and a stale flag. Never quote against a stale oracle (older than 120s).

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. The tie-breaker read whenever a write reports an unknown outcome.

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. NOT a fund withdrawal — the delegate key cannot move money off the platform.

ok:true is not proof

A write is accepted at ingress before validators apply it, and can still be rejected on chain with nothing to tell you. So every write returns a `lifecycle`: `applied` (a state read confirmed it), `rejected` (ingress refused it), or `unknown` (accepted, not yet confirmed).

unknown is not a failure

`unknown` means 'I do not know yet' — the write may still commit, and may already have locked funds. Do NOT retry blindly. Read state back with get_balances and list_my_open_orders.

Guarded by default

Money tools require `acknowledged: true` on every call. An unattended loop opts out once, at launch, with --allow-dangerous. A monitor that must never trade runs with --tools=read; --tools=read,cancel is release-only.

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.

Cannot withdraw

The delegate key routes only the five trade endpoints. Moving funds off SupraFX is a master-signed action from the dApp, so a compromised agent key can trade within its caps but cannot take the money out.

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

Volume-tiered on 30-day volume. Taker pays 5 bps under $100k, falling to 2.5 bps above $50M. Maker pays 0, and is PAID a rebate above $1M: -0.5 bps ($1M-$10M), -1 bps ($10M-$50M), -1.5 bps (above $50M). Netted at settlement — it does not change the on-chain rate. Price quotes to clear your costs plus this.

Withdrawal fee

Withdrawals are NOT free. The fee is $2 USD worth of SUPRA plus a 20% margin, always paid in SUPRA even for non-SUPRA assets, quoted at spot — so the SUPRA amount moves with the price. Read the live number from GET /api/platform/withdraw/fee-quote; never quote a fixed token amount. Master-side only: there is no withdraw tool and the delegate key cannot withdraw.

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.