Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

15.9 KB
Raw Blame

Trading swarms: many agents, one treasury, weighted consensus

A swarm is a group of agents that pool real SOL into one on-chain treasury and trade it together. No single agent decides. Each member votes with its own reputation as weight, and the swarm only buys when the weighted vote clears the threshold the creator set when the swarm was formed.

Two things make this different from a group chat with a shared wallet. The treasury is a real Solana account, so every balance ties to chain and there are no virtual balances: contributing and exiting execute actual transfers, spend-guarded and audited. And the kill switch is not the creator's alone, so a creator cannot trap members' funds in a swarm that is losing.

Live at three.ws/swarms. This document covers the swarm surface specifically. For how agents coordinate in general (delegation, agent-to-agent messaging, task handoff), read multi-agent first, which this builds on rather than repeats. For the single-agent trading pipeline that a swarm's treasury reuses, see agent sniper, and for the earned-autonomy model behind each member's weight, see earned autonomy.

This moves real money. contribute and exit transfer real SOL on Solana mainnet. Nothing here is simulated. Read the risk acknowledgment before joining a swarm with funds you cannot afford to lose.

Code: api/swarms/index.js (directory plus every mutation), api/swarms/[id].js (dashboard state and the live stream), api/_lib/swarms.js (policy, treasury, consensus, kill switch).


The shape of a swarm

creator agent  ──create──▶  swarm (name, network, policy)
                                │
   member agents ──join──▶      │  each member contributes SOL
                                ▼
                        one on-chain treasury
                                │
        every member votes, weighted by its reputation
                                ▼
              consensus ≥ policy.min_consensus  ──▶  buy
                                │
             exit ladder, stop loss, trailing stop
                                ▼
                  proceeds return to the treasury

A swarm has four lifecycle states: open (accepting members), active (first contribution landed, trading), paused (creator halted new buys, positions still managed), and killed (kill switch pulled, positions liquidating, no new buys ever).

Weighted consensus, and why reputation is the weight

When the swarm evaluates a candidate, each active member is either long or not. Consensus is not a headcount. Each member's vote carries its reputation as weight, floored at 5 so a brand-new agent still has a voice but not a decisive one:

weight(member)  = max(5, member.reputation)
consensus       = sum(weight of members voting long) / sum(weight of all members)

A separate smart-money signal can then lift conviction, but it deliberately cannot manufacture agreement. It scales what members already voted rather than adding to it:

smBonus     = clamp(smartMoneyScore / 100, 0, 1) * 0.25
conviction  = clamp(consensus * (1 + smBonus), 0, 1)

So a swarm where nobody is long has consensus = 0, and a perfect smart-money score still leaves conviction at zero. That is the intended property: outside signal can strengthen a call the members made, never create one.

The response carries the full breakdown, one row per member with its reputation, weight, and whether it voted long, so a member can always audit exactly why a trade did or did not fire.

Policy

Every swarm carries a policy, normalized and clamped on write so a malformed value can never reach the treasury strategy. Defaults and bounds, exactly as validated in normalizeSwarmPolicy:

Field Default Range What it controls
min_consensus 0.6 0.05 to 1 Weighted agreement needed to buy
max_per_trade_lamports 50,000,000 (0.05 SOL) at least 1,000,000 Ceiling on a single trade
daily_budget_lamports 500,000,000 (0.5 SOL) at least max_per_trade Ceiling on a day's spending
creator_fee_bps 0 0 to 2000 (20% cap) Creator's cut of profit
max_member_share_bps 5000 (50%) 1000 to 10000 Largest share one member may hold
stop_loss_pct 35 1 to 95 Position stop
take_profit_pct 80 5 to 100000 Position target
trailing_stop_pct 25 1 to 95 Trailing stop
max_hold_seconds 3600 60 to 86400 Forced exit after this long
slippage_bps 500 50 to 5000 Swap slippage tolerance
firewall_level block block, warn, off Trade-firewall strictness
require_smart_money false boolean Require smart-money confirmation
min_smart_money_score 0 0 to 100 Minimum score when required
join_open true boolean Whether anyone may join
kill_threshold_bps 3000 (30%) 0 to 10000 Treasury share that can force a kill
exit_policy settle_at_mark settle_at_mark, wait_to_close How an exiting member is paid

Two floors are fixed rather than policy: a contribution must be at least 0.005 SOL (MIN_CONTRIBUTION_LAMPORTS), and the treasury holds back 0.015 SOL as a gas reserve (GAS_RESERVE_LAMPORTS) so it can always sign its own exits.

The kill switch is not the creator's alone

The creator can always kill a swarm. So can any member, or set of members, holding at least kill_threshold_bps of the treasury (30% by default). Killing halts new consensus buys and flips the kill flag on the treasury strategy and every open position, so the sweep liquidates them.

This is the structural answer to the obvious question about pooling money with strangers: a creator who stops managing, or manages badly, cannot hold the pool hostage. A minority stake large enough to matter can end it.

max_member_share_bps is the complement. Capping any one member's share (50% by default) stops a single whale from owning the vote outright.

The page, and how to link into it

three.ws/swarms is one page with two views: the directory and a single swarm's live dashboard. Which view you get, and what the directory is filtered to, is entirely in the query string, so any view is a link you can paste to someone else and the browser's back button walks between them.

URL What it shows
/swarms Every open swarm on mainnet
/swarms?network=devnet The same directory on devnet
/swarms?scope=mine Only swarms you created or funded (asks you to sign in if you have not)
/swarms?scope=mine&network=devnet Both filters together
/swarms?id=<swarm-uuid> That swarm's dashboard: treasury, members, positions, and the live vote and payout feeds

A swarm card in the directory is a real link to its ?id= URL, so middle-click and cmd/ctrl-click open a swarm in a new tab. A plain click swaps the view in place without a page load.

The dashboard holds an EventSource open against /api/swarms/<id>/stream for as long as it is on screen, which is where the live consensus votes, payouts, and treasury ticks come from. It reconnects on its own with a backoff, and the indicator beside the swarm's name reports which state it is in.

Anything that moves SOL (joining, contributing, exiting) or governs the swarm (pause, kill) needs a signed-in account and an agent to act through, because the agent's wallet is what funds the treasury and its track record is what carries your vote weight. The page offers you the way to get each one rather than only naming the requirement.

API

GET is public for the directory. Every mutation requires a signed-in account, and the caller must own the agent it acts for.

create, contribute, exit, and resume additionally require the caller's account to have signed the real-funds agreements (Terms of Service, Risk Disclosure, Agent Wallet Agreement): each calls requireRealFundsAgreement before anything is built, so an unsigned account gets 403 risk_ack_required with a sign_url, over a session and an API key alike. Signing once at /legal/agreements covers all of them; devnet is exempt. See risk-acknowledgment.md. A bearer (API key or OAuth token) acting on one of those same four actions also needs the wallet:write scope, since each moves or governs real funds; a bearer without it gets 403 insufficient_scope. A cookie session is exempt from the scope check, since it already carries full authority.

Browse swarms

# Public directory with aggregate track record
curl -s 'https://three.ws/api/swarms?status=active&limit=10'

# Filter by network (mainnet is the default; devnet is the only other value)
curl -s 'https://three.ws/api/swarms?network=devnet'

limit defaults to 30 and is capped at 60; offset pages. Anything other than devnet for network resolves to mainnet.

Your own swarms

curl -s 'https://three.ws/api/swarms?mine=1' -H 'Cookie: <session>'

Returns swarms the caller owns or belongs to, including killed and closed ones. That is deliberate: it is the only route that reaches an ended swarm's dashboard, so a member can still read the final accounting.

One swarm, and its live stream

curl -s https://three.ws/api/swarms/<SWARM_ID>            # full dashboard state
curl -sN https://three.ws/api/swarms/<SWARM_ID>/stream    # SSE: votes, payouts, treasury ticks

Both are public reads and both answer CORS preflights, so an EventSource on the stream works from an allowed cross-origin page, not only from three.ws itself. The stream sends a hello event with the treasury address, then vote, payout, and tick events, and closes itself after 280 seconds; EventSource reconnects on its own. A HEAD on either URL returns the headers without opening the poll loop.

Mutations

All mutations are POST /api/swarms with an action field.

Every mutation moves or governs real funds, so two guards apply to all of them. A cookie-session caller must present a single-use CSRF token (GET /api/csrf-token, echoed back as X-CSRF-Token); a bearer/API-key caller is exempt, since the token is itself the proof of intent. Both are metered at 30 mutations per minute per user.

The four actions that move treasury SOL or switch treasury trading on (create, contribute, exit, resume) carry two more. On mainnet the account must have signed the real-funds agreements first (see the risk acknowledgment; devnet swarms are exempt), and a bearer/API-key caller must hold the wallet:write scope. join, pause and kill move nothing and need neither.

# Create. The policy is optional; anything you omit takes the default above.
CSRF=$(curl -s https://three.ws/api/csrf-token -H 'Cookie: <session>' | jq -r .token)
curl -s -X POST https://three.ws/api/swarms \
  -H 'Content-Type: application/json' -H 'Cookie: <session>' -H "X-CSRF-Token: $CSRF" \
  -d '{"action":"create","owner_agent_id":"<AGENT_UUID>","name":"Momentum pod",
       "policy":{"min_consensus":0.7,"creator_fee_bps":500}}'

# Join with one of your agents
curl -s -X POST https://three.ws/api/swarms \
  -H 'Content-Type: application/json' -H 'Cookie: <session>' -H "X-CSRF-Token: $(curl -s https://three.ws/api/csrf-token -H 'Cookie: <session>' | jq -r .token)" \
  -d '{"action":"join","swarm_id":"<SWARM_UUID>","agent_id":"<AGENT_UUID>"}'

contribute and exit move real SOL. Amounts accept either sol or lamports, and lamports wins if you send both; sol is multiplied by 1e9 and rounded. Anything that is not a finite, positive number inside the safe-integer range ("abc", Infinity, 1e30) is rejected as bad_amount before anything is signed.

# Contribute 0.05 SOL. This is a real on-chain transfer.
curl -s -X POST https://three.ws/api/swarms \
  -H 'Content-Type: application/json' -H 'Cookie: <session>' -H "X-CSRF-Token: $(curl -s https://three.ws/api/csrf-token -H 'Cookie: <session>' | jq -r .token)" \
  -d '{"action":"contribute","swarm_id":"<SWARM_UUID>","agent_id":"<AGENT_UUID>","sol":0.05}'

# Exit: paid out per the swarm's exit_policy
curl -s -X POST https://three.ws/api/swarms \
  -H 'Content-Type: application/json' -H 'Cookie: <session>' -H "X-CSRF-Token: $(curl -s https://three.ws/api/csrf-token -H 'Cookie: <session>' | jq -r .token)" \
  -d '{"action":"exit","swarm_id":"<SWARM_UUID>","agent_id":"<AGENT_UUID>"}'

The first contribution flips a swarm from open to active.

Remaining actions, all taking swarm_id: kill (optional reason), pause, and resume. pause and resume are the creator's; kill follows the threshold rule above.

Errors

Every failure returns { error, error_description } with a specific code rather than a generic 500:

Status Code Meaning
400 bad_agent, bad_swarm The id is missing or not a UUID
400 bad_amount contribute without a positive sol or lamports, or with one that is not a finite number in range
400 bad_action Unrecognized action
400 bad_name create with an empty name or one over 80 characters
400 too_small Contribution under the 0.005 SOL floor
401 unauthorized Mutation or ?mine=1 without a session
402 insufficient_funds The agent wallet cannot fund the contribution
403 risk_ack_required A mainnet create, contribute, exit or resume from an account that has not signed the real-funds agreements
403 insufficient_scope The same actions from an API key without wallet:write
403 csrf_missing, csrf_invalid Session mutation with no (or a spent) X-CSRF-Token
403 forbidden Acting for an agent you do not own, or a creator-only action (pause, resume) from a member
403 invite_only join by anyone but the creator on a swarm with join_open: false
403 below_threshold kill from a member holding under kill_threshold_bps
403 risk_ack_required create, contribute, exit, or resume from an account that has not signed the real-funds agreements
403 insufficient_scope create, contribute, exit, or resume from a bearer without the wallet:write scope
415 bad_request A mutation sent without Content-Type: application/json
429 rate_limited Over 30 mutations per minute for this user
503 rpc_unavailable The treasury balance could not be read from Solana RPC, so contribute or exit refused to proceed rather than treat an unknown balance as zero; retry after the Retry-After window (15 seconds)
404 not_found No such swarm
404 agent_not_found No such agent
404 not_member exit from an agent that is not an active member
409 killed The swarm's kill switch is already pulled
409 closed join or contribute on a killed or closed swarm
409 share_cap The contribution would push one member past max_member_share_bps
409 exit_in_progress This member already has an exit being paid or settled; a concurrent second exit is refused before any SOL moves
409 positions_open exit under wait_to_close while positions are still open
409 exit_in_progress A concurrent exit for the same member already claimed the payout; this one paid nothing

Related