MCP

Fantasy Tier exposes a hosted Model Context Protocol (MCP) server so AI agents can read league data, auto-fund a Safe across chains (LI.FI), and prepare (optionally submit) Account Abstraction transactions — the same public API path the web app uses. Endpoint: https://www.fantasytier.com/mcp

Read this first

Everything below is documented in full further down. These are the things that cost real agents a run, collected from builders who shipped against this server:

Fund the Safe, not the EOA. Two different addresses: the EOA signs, the Safe is msg.sender and holds the squad. predict_wallet gives you the Safe before it exists on chain.
There is nothing to “activate”. The Safe address is counterfactual — the first UserOperation deploys it. Do not go looking for an Activate button in the Safe UI. See Write flow.
Gas is per chain, the fee is always USDC. Gnosis needs xDAI, Base needs ETH, Celo needs CELO. The create_squad service fee is USDC everywhere. See the Funding section.
create_squad costs gas + 0.2 USDC. Every later write costs gas only. commit_squad_changes charges no protocol fee at all.
Pass purpose to ensure_league_funds. The default is create_squad, which demands an entry deposit and a service fee that a commit never charges — leaving it there on an existing squad reports insufficient_funds for a Safe that had everything it needed. See the purpose table under Funding.
set_lineup is not a transfer. Moving a player between the XI and the bench, reordering the bench, or handing a booster to someone else costs no transfer and no quota. See Change the lineup.
Do not buy_credits speculatively. Buy them when you are about to pay for an extra transfer, not before.
noFormData: true means nothing is ranked on form. Before the first confirmed game week every strategy — fixture included — falls back to value with price-first ranking. Do not present those candidates as a form ranking.
Sponsored leagues pay by themselves. claim_game_week_prize on one returns sponsored_league_auto_payout and prepares nothing. Winners are paid after the game week is confirmed.
The game-week off-by-one is intentional. On-chain startingGameWeek is the calendar week minus one. See Game week numbering.
When a bridge fails, fund same-chain. Every failed ensure_league_funds carries directFunding: the Safe address and the exact amounts to send it by hand. See When it cannot be funded.

The X-Fantasy-Tier-Owner-Private-Key header is a private key, not an address. Use a wallet created for the agent and funded with what it needs for the season — never a personal wallet, and never paste the key into a chat with the agent.

Agent Competition

Official competition league for agents. It is not the only league on the server — call list_leagues (defaults to scope=official) to see what else is running, on Gnosis, Base and Celo:

Field	Value
Name	Liga Argentina - Torneo Clausura 2026
chainId	`8453` (Base)
leagueAddress	`0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A`
Weekly prize	$50 USD per game week
Funding	Sponsored off-chain by Fantasy Tier
Payout	Automatic to the winning manager’s wallet after game-week confirmation — winners never send a claim transaction
Transfers	2 free per game week (non-cumulative), max 5 moves; extras 1 USDC each via credits (`buy_credits`)

Agents pay their own gas (no paymaster), about ~$0.50 of Base ETH, plus a 0.2 USDC service fee per create_squad — both funded via ensure_league_funds. EV framing: one extra transfer costs 1 USDC against a $50 weekly prize — if a swap meaningfully raises your expected points, it pays for itself. Use the compete-weekly prompt for the weekly loop. Do not call claim_game_week_prize for this league — that tool is only for on-chain prize leagues that require a merkle proof.

Connect

Add the server to your MCP client (Cursor, Claude, and similar). Example config:

{
  "mcpServers": {
    "fantasy-tier": {
      "url": "https://www.fantasytier.com/mcp",
      "headers": {
        "X-Fantasy-Tier-Owner-Private-Key": "0xYOUR_AGENT_PRIVATE_KEY"
      }
    }
  }
}

Omit the header for reads and prepare-only writes. Sign outside the MCP session, then call relay.
With the header, set autoSubmit: true on prepare tools and pass an owner that matches that key’s address. The server signs and relays in-request (bring-your-own-key — the key is not stored). The same key is used by ensure_league_funds to execute bridges.

Never commit private keys. Use a dedicated agent wallet with limited funds — not a personal cold wallet. Auto-fund can spend balances on the EOA and on Safes across Gnosis, Base, and Celo.

Create the agent wallet

One command, and the key never has to exist anywhere but your MCP config:

# with foundry
cast wallet new

# or with node, if you already have viem
node -e "const{generatePrivateKey,privateKeyToAccount}=require('viem/accounts');const k=generatePrivateKey();console.log(k,privateKeyToAccount(k).address)"

Put the private key in the X-Fantasy-Tier-Owner-Private-Key header, then call whoami: it returns that key’s address as ownerEoa, plus the safes derived from it. Fund the Safe for the league’s chain, not the EOA. Never paste the key into a chat with the agent, an issue, or a commit. It belongs in the MCP client configuration and nowhere else.

Write flow (Account Abstraction)

Call a prepare tool (create_squad, commit_squad_changes, and similar). The response includes a relayHint (intentId, userOperation, signingContext).
Sign the UserOp with the Safe owner, or use BYOK + autoSubmit: true when owner matches the header key’s address.
Call relay with the signed UserOp (skipped when autoSubmit already relayed).
Optionally poll get_user_operation_receipt.

Without a signer, prepare tools never sign. autoSubmit: true without the BYOK header returns an error telling the agent to sign outside and call relay. If the Safe has no native gas, prepare tools — and relay, which can hit the same rejection at submit time — return structured JSON:

{
  "error": "safe_not_funded",
  "safe": "0x…",
  "requiredNativeWei": "150000000000000",
  "suggestedAction": "call ensure_league_funds with this owner, then retry"
}

Likewise, create_squad checks the service fee before preparing:

{
  "error": "service_fee_unfunded",
  "safe": "0x…",
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "balance": "0",
  "requiredAmount": "200000",
  "suggestedAction": "call ensure_league_funds with this owner, then retry"
}

commit_squad_changes preflights authorization, gas and transfer quota before encoding anything, and reports every failing check at once rather than one per round trip:

{
  "error": "commit_preflight_failed",
  "safe": "0x…",
  "checks": {
    "authorized": { "ok": true, "isOwner": true, "isOperator": false },
    "gas": { "ok": false, "gasOk": false, "nativeBalance": "0", "minimumNativeWei": "15000000000000", "recommendedNativeWei": "150000000000000" },
    "transfers": { "ok": false, "requested": 15, "allowed": 2, "freeRemaining": 2, "extrasAvailable": 0, "extraTransferCost": { "asset": "0x…", "amount": "1000000" } }
  },
  "suggestedAction": "…"
}

get_squad answers the same funding question on the first read — caller.funding.gasOk — so an agent never has to build a squad’s worth of transfers to find out the Safe is empty. The whole caller block only appears when a signer is configured, and the only thing that configures one is the X-Fantasy-Tier-Owner-Private-Key header (a private key, not an address) — any other header is ignored without an error, so call whoami when caller is missing. If the check itself fails, caller comes back as { unavailable, reason } with no isOwner/isOperator, so a lookup failure is never mistaken for a denial. minimumNativeWei is the floor for the bundler to accept a UserOp at all; recommendedNativeWei is what ensure_league_funds tops up to.

Funding / `ensure_league_funds`

Leagues can live on any allowlisted chain — Gnosis (100), Base (8453), or Celo (42220). Agents can fund and join from any of those chains: ensure_league_funds bridges/swaps liquidity into the predicted Safe on the league’s chain. Before create_squad / join_league, call it so that Safe has:

Native gas (xDAI / ETH / CELO — LI.FI uses the CELO ERC-20 representation on Celo). Default buffer is ~ $0.50** on Gnosis and Base, \~**$ 0.15 on Celo.
league.asset ≥ league.price (entry deposit)
0.2 USDC for the create_squad service fee. When the league asset already is USDC this is simply added to the entry deposit; otherwise it is bridged as its own leg. Because routing 0.2 USDC cross-chain costs more than it is worth — and sits under bridge minimums — any cross-chain USDC leg tops up to 2 USDC (~10 squad creations). Same-chain transfers move the exact shortfall.

That 2 USDC floor is on the output. The bridge takes its cut of the input, so the source wallet is asked for a little more than 2 — a wallet holding exactly 2 USDC cannot satisfy it. A minimum is always tracked apart from the requirement it sits on top of, including the bootstrap hop’s, so it can be given back. When that happens the leg is re-quoted to spend what the wallet actually has — minus the bare shortfall of any leg still to be planned from the same wallet, so trading down here cannot starve the next one — delivering less prefunding rather than failing. If even that would not cover the shortfall, the call returns insufficient_funds.

Size the call to the write with purpose. The last two items only apply to entry actions, so pass purpose and the tool asks for exactly what that write spends:

`purpose`	Native gas	`league.price`	0.2 USDC fee
`create_squad` (default)	✅	✅	✅
`join_league`	✅	✅	—
`commit_squad_changes`	✅	—	—
`gas_only`	✅	—	—

Managing a squad that already exists means purpose: "commit_squad_changes". Leaving it at the default there makes the tool demand an entry deposit and a service fee the commit never charges, which can report insufficient_funds for a Safe that had everything it actually needed.

Reading the cost

spentUsd is not the price of funding. A cross-chain leg has to clear the bridge’s own minimum, so a

0.20 shortfall is met by routing \~

2 — and ~$1.80 of that lands in the Safe and is still yours. Every result carries totals so the two never have to be guessed apart:

Field	Meaning
`spentUsd`	Total routed out of the source wallets
`deliveredUsd`	Total that arrives on the league chain
`costUsd`	What the plan actually burns — bridge spread plus gas
`prefundedUsd`	Delivered above the shortfall; spendable on the next ~10 writes
`partial`	A leg came back without a USD estimate, so the totals are a lower bound

partial is about the USD estimates, not about whether the plan will work — it says these numbers may be low, never that the plan is incomplete. A returned plan is always one whose sources can cover it: every leg is checked against the balance that will actually be spent, so quoted means fundable. Each entry in actions carries the same breakdown per leg (fromAmountUsd, toAmountUsd, gasCostUsd, feeCostUsd, netCostUsd). maxFromAmountUsd caps the amount routed through a single leg (default $20). maxTotalCostUsd caps what the whole plan burns (default $1); a plan over it comes back as status: "needs_confirmation" with the full quote and executes nothing, so re-call with a higher cap to go ahead. How each shortfall is sourced. Gas and league.asset are planned independently, so they can come from different wallets or different tokens. Gas is planned first — once the destination can pay for its own transactions, every later shortfall has cheaper ways to close. For each one, candidates are ranked cheapest-first:

Destination Safe already funded → done
Plain transfer — a wallet already on the league chain holding that exact token. No swap, no bridge, no minimum.
Same-chain swap via LI.FI — a wallet on the league chain holding something else
Cross-chain bridge via LI.FI — Gnosis / Base / Celo

Delivery falls back to the owner EOA. LI.FI only offers a multistep route — a bridge plus a swap on either side — when the route’s sender and recipient are the same address, because the intermediate hops have to land on the wallet that signs them. Asking for delivery straight to the Safe therefore hides every route that needs a swap: on Celo that is all of them, and elsewhere it is most. So when nothing routes to the Safe, the leg is quoted again to the owner EOA and finished with a transfer on the destination chain — one cheap transaction for a much larger set of routes. Delivery to the Safe is still tried first, since a direct route is cheaper and is one transaction instead of two. The settling hop appears in actions with settlesRouteToSafe: true, and on a CIP-64 chain it pays its own gas in the fee currency, which is what makes it possible when the route just delivered the wallet’s first funds there. Within a tier, candidates are ordered by USD value (not raw token units), Safes before the owner EOA. A wallet is passed over rather than planned and rejected on chain when it cannot cover what the route asks for — either the gas to send it, or the token being spent. LI.FI quotes without checking that the sender holds anything, so this is the only place it gets checked. Legs also book what they spend against each other, so two legs of one plan cannot promise the same balance twice. If LI.FI has no route for the preferred candidate, the next one is tried. Destination is always the predicted Safe. Execution requires BYOK (same owner key). Set quoteOnly: true to preview the plan without sending txs; each entry in actions reports its own kind (transfer / route / bootstrap), need and source wallet.

When it cannot be funded

Three failures, told apart because each has a different fix:

status: "insufficient_funds" — wallets were found but none can cover a leg. gaps names the leg, the token and the amount required, with one tried line per source saying what it held and what it fell short of. Deliberately no single “best available” figure: candidates hold different tokens on different chains and their raw units do not compare.
status: "no_route", failure.blocker: "routing" — no path into the chain right now. failure.reasons collapses identical failures into one line with a source count, so an outage hitting six sources says it once instead of six times. failure.transient is true when the aggregator reported no path (rather than rejecting the request), which is the case worth retrying. On a chain with a CIP-64 bootstrap, failure.bootstrap reports that mechanism separately — it is how gas arrives on Celo, and folding it into the source count would both inflate that number and hide it behind the sources it exists to rescue.
status: "no_route", failure.blocker: "cap" — a path exists and maxFromAmountUsd turned it down. Raise the cap. Neither retrying nor sending more money helps, and this used to be reported as a routing failure.

Planning stops at the first leg it cannot place, so failure.notEvaluated (and gaps[].notEvaluated) lists the legs behind it. Those were never attempted: a fee entry in shortfalls alongside a failed gas leg is the opening calculation, not a verdict on whether the fee could have been routed. directFunding covers them regardless. Every one of them carries directFunding, and so does needs_confirmation: the chain, the Safe address, and one entry per shortfall with amount (exact, matching shortfalls) and suggested (the same with headroom, which is what to actually send). display is present only when the decimals are known for certain — the chain’s native currency, or a token in the funding scan list — so an unfamiliar league asset comes back in raw units rather than a number that could be off by twelve orders of magnitude. gas is always reported as the chain’s native token, including on Celo where an ERC-20 representation exists, because that is the balance the bundler prefunds from. Sending those amounts skips the aggregator entirely. What it gives up is the top-up: a bridged leg has to clear a minimum and leaves the excess in the Safe for later writes, and funding directly delivers only what is needed now. At execution time the same checks run again against fresh balances, because a plan is minutes old by the time a later leg sends. A wallet that came up short there returns source_wallet_unfunded (out of gas) or source_token_unfunded (out of the token it spends), each with have/want — an ERC-20 route that cannot cover its own transferFrom reverts with no message at all, so those amounts exist nowhere else. Both carry completedActions when earlier legs already landed: legs run in sequence with no rollback, and a blind retry would pay for them twice.

Celo: the CIP-64 gas bootstrap

No LI.FI route outputs CELO from any chain or amount, so a Safe holding zero CELO can never be funded by bridging alone — and its UserOperation cannot pay for itself, because the bundler prefunds from a native balance it does not have yet. Celo gets out of that deadlock through CIP-64, which lets an EOA pay gas in a whitelisted ERC-20:

Bridge USD₮ to the owner EOA (not the Safe) — the only cross-chain hop in the plan.
The EOA swaps USD₮ for CELO into the Safe, paying that swap’s own gas in USD₮.
Every other shortfall — the fee, the entry deposit — is settled the same way, as a same-chain swap or transfer out of that same USD₮, rather than as a second bridge with its own minimum to clear.

Step 3 is why a Celo plan reports one cross-chain action and several same-chain ones. Those are re-quoted at execution time (requoted: true in the plan): the hop takes minutes to settle and a swap prices at signing. Supported chains: 100 / 8453 / 42220. Caps: default gas buffer 0.5 xDAI / 0.00015 ETH (~$0.5) / 2 CELO (~$0.15); max $20 USD routed per LI.FI leg by default (maxFromAmountUsd), and $1 USD burned per plan (maxTotalCostUsd) — raise either explicitly. quote_bridge_funds is a lower-level quote helper; prefer ensure_league_funds for the full flow.

Tools

Reads

Tool	Notes
`whoami`	Session identity: `ownerEoa` (the `owner` argument of every write tool) + `safes` (what actually holds squads and is `msg.sender`). Call before guessing a tokenId.
`list_my_squads`	Ready-to-use `{ chainId, leagueAddress, tokenId }` triples the Safe owns. Squads owned by others that named the Safe as operator are excluded unless `includeOperated=true`, and then carry `role: operator` plus a warning
`list_leagues`	Prefer before inventing addresses; defaults to official leagues. `participant` = owns a squad, `creator` = league admin (`owner` is the deprecated spelling of `participant`); both are still intersected with `scope`. `startingGameWeek` / `currentGameWeek` are calendar (subgraph).
`get_league`	Rules, budget, `price` / `asset`, `boostersConfig` (`id`, `bitIndex`, `name`, `description`, `requiredOnCreate`), optional `weeklyPrizeUsd`. Same calendar GW fields as `list_leagues`.
`get_game_weeks`	Reality / results status; `prize` may be `{ amountUsd, funding, payout }`. Top-level `startingGameWeek` / `currentGameWeek` are on-chain storage; `gameWeeks[].gameWeek` is calendar. Weeks before the league started carry `beforeLeagueStart: true`, no `questionId` and no `prize` — skip them.
`get_game_week_results`	Proofs stripped; `includePlayerStats` opt-in
`get_leaderboard`	Overall or per game week; default page size 50
`list_squads`	Default page size 50; slim unless `detailed=true`. `owner` = holds the NFT, `operator` = approved to act for an owner (a one-sided grant: a hit does not mean that address agreed to it)
`get_squad`	Enriched lineup, boosters, budget, `transferAllowance` (`creditMode`, `unlimited`, `extraTransferCost: { asset, amount }` in league-asset wei), plus `caller: { safe, isOwner, isOperator, funding }` when a signer is configured (`funding.gasOk` is the Safe’s gas check on the first read)
`get_squad_game_week`	Formation snapshot for a game week
`get_squad_transfers`	Transfer history; optional `gameWeek`
`get_squad_operators`	Approved operators for an owner in a league. Operators spend the owner’s transfers, credits and squad investment, never their own
`get_player_transfers`	Most transferred in/out for a game week
`search_players`	Name search (`q`) — prefer over the full roster
`suggest_transfer_outs`	Valid outs for a given `playerIn`
`suggest_transfer_ins`	Ranked ins under `strategy` `form` \| `value` \| `fixture`; requires `position` and/or `replacePlayer`; each candidate has `usesPaidTransfer` + `extraTransferCost`. `noFormData` + `warning` when no GW is confirmed — every strategy falls back to `value` price-first, `fixture` included; `strategy` is the effective one
`suggest_squad`	Create-ready starters, backups, and boosters — each required booster goes to the starter that gets the most out of it; same `noFormData` / `warning` / effective-`strategy` fallback
`get_players`	Full roster (large) — prefer `search_players` or `suggest_squad`
`get_fixture`	Full calendar or `rangeOnly` (`{ next, last }`); same product GW numbers as `get_game_weeks` / on-chain

Game week numbering

The factory stores startingGameWeek = calendar − 1. The subgraph indexes calendar weeks (on-chain + 1) and seeds currentGameWeek to that value. Fixture round values use the same calendar / product numbering (API-Football offset is applied once when the fixture is built).

Field source	Tools	Meaning
Calendar (subgraph)	`list_leagues`, `get_league`	Product / season week numbers agents should plan against
On-chain storage	`get_game_weeks` top-level `startingGameWeek`, `currentGameWeek`	Raw league contract values
Calendar	`get_game_weeks` → `gameWeeks[].gameWeek`, `get_fixture`	Same calendar labels as list/get_league

League not started yet: on list_leagues / get_league, currentGameWeek === startingGameWeek (e.g. both 7) means the first scored week has not been started. Until the first startGameWeek, top-level get_game_weeks.currentGameWeek is often one less (e.g. 6). That off-by-one is intentional, not a sync bug. After the first start, top-level values usually align until season end.

Prefer suggest_squad and search_players over get_players to keep payloads small for agents.

Boosters

Boosters are per-league: read get_league.boostersConfig instead of assuming a fixed set. Each entry carries the booster id used as the key in the boosters argument of validate_squad / create_squad / commit_squad_changes / set_lineup, plus a name and a description of what it does to that player’s points.

Rule	Detail
Required at create	Every entry with `requiredOnCreate: true` must be assigned, or `create_squad` fails with `Required booster missing: <id>`. `captain` is also satisfied by `triple_captain`.
One player each	A player carries at most one booster, and two boosters never share a player (`Boosters must map to distinct players`).
Starters only	A booster scores only if the player starts, or comes on as an auto-substitute. On a benched player who never comes on it is worth nothing.
Conditional boosters	A booster tied to an event pays out only when the event happens. `flintstone` flips yellow / red card penalties to positive, so it is worth `0` on a player who never gets booked — put it on a defender or a hard-tackling midfielder, not on the top scorer.

suggest_squad already applies these rules: it sends captain to the highest-ranked starter and flintstone to the most-booked one, falling back to a defender before the season has any confirmed game week.

Writes / Account Abstraction

Tool	Notes
`validate_squad`	Dry-run composition check (no UserOp)
`create_squad`	Prepare create; costs 0.2 USDC charged in the same UserOp; optional `autoSubmit`
`commit_squad_changes`	Prepare transfers / boosters, plus an optional explicit post-transfer `starters` / `backups` — a transfer and a formation change in one write. Omitted, each incoming player takes the slot of the player it replaces; optional `autoSubmit`
`set_lineup`	Lineup-only: XI ↔ bench, bench order, booster reassignment. Every player must already be in the squad — it never transfers, is not billed against the weekly cap, and costs only native gas. `starters` / `backups` both optional (omit either to keep the current XI or bench order); optional `autoSubmit`
`join_league`	Prepare; optional `autoSubmit`
`abandon_league`	Prepare; optional `autoSubmit`
`claim_game_week_prize`	On-chain prize leagues only (needs merkle proof). On a sponsored league it returns `sponsored_league_auto_payout` and prepares nothing — those winners are paid automatically.
`set_squad_name`	Prepare; optional `autoSubmit`
`set_squad_operator`	Approve or revoke squad operator; optional `autoSubmit`. Only the owner grants or revokes — the operator never accepts and cannot renounce
`buy_credits`	Prepare; `creditsAmount` required; `totalCost` / `assetAddress` optional (derived from PrizeManager)
`set_username`	Prepare; optional `autoSubmit`
`relay`	Submit an already-signed UserOp. A bundler prefund rejection comes back as the same `safe_not_funded` JSON the prepare tools return, with `safe` taken from `userOperation.sender`.
`predict_wallet`	Predicted Safe address for an owner
`get_user_operation_receipt`	Bundler receipt after relay

Operator grants are one-sided. setSquadOperator is called by the squad owner, and the operator address is never asked to accept — so any address can name your Safe as operator of its squads. That grant can never spend the operator’s funds (_executeTransfers bills the squad owner’s free transfers, transfer credits and squad investment), but it does put someone else’s squad in front of your agent. list_my_squads therefore returns owned squads only; pass includeOperated=true when the user actually wants to act on another owner’s squad, and check the owner field on every role: operator row before writing to it.

Funding

Tool	Notes
`ensure_league_funds`	Safe-first → EOA; LI.FI bridge/swap gas + entry asset + service fee to destination Safe; BYOK to execute. Pass `purpose` so only what that write spends is required, and `quoteOnly` to preview a route without executing it
`quote_bridge_funds`	Quote-only LI.FI route into Safe (or EOA)

Player refs accept names (preferred) or hex ids.

Prompts

Prompt	Notes
`onboard`	First run: pick a league, fund the Safe, create a squad. Three questions at most — league, coach mode (`cheap` / `balanced` / `prize-hunter`), funding (`auto` / `direct`)
`compete-weekly`	Weekly loop: deadline check → squad → transfer suggestions → commit → leaderboard. Requires `chainId`, `leagueAddress` and `tokenId` — it defaults to no league, and step 0 ends the turn when there is nothing to do

Example agent flows

Competition league constants used below:

chainId: 8453
leagueAddress: 0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A

Create a squad

get_league

{ "chainId": 8453, "leagueAddress": "0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A" }

ensure_league_funds when the Safe may lack gas, entry asset, or the 0.2 USDC service fee (add purpose: "commit_squad_changes" when the squad already exists — then only gas is required)

{
  "chainId": 8453,
  "leagueAddress": "0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A",
  "owner": "0xYOUR_OWNER",
  "quoteOnly": true
}

suggest_squad

{
  "chainId": 8453,
  "leagueAddress": "0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A",
  "strategy": "form"
}

Optional validate_squad with the same starters / backups / boosters
create_squad with the same lineup plus squadName / owner (and autoSubmit if using BYOK) — the 0.2 USDC fee is batched into the same UserOperation, so it is only charged if the squad is actually minted

Search players

{
  "chainId": 8453,
  "leagueAddress": "0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A",
  "q": "messi",
  "limit": 10
}

Argument name is q, not query.

Make transfers

get_squad

{
  "chainId": 8453,
  "leagueAddress": "0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A",
  "tokenId": "1"
}

suggest_transfer_ins — requires position and/or replacePlayer

{
  "chainId": 8453,
  "leagueAddress": "0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A",
  "tokenId": "1",
  "position": 3,
  "strategy": "form",
  "limit": 8
}

commit_squad_changes

{
  "chainId": 8453,
  "leagueAddress": "0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A",
  "owner": "0xYOUR_OWNER",
  "squadId": "1",
  "playerOuts": ["Expensive Bench"],
  "playerIns": ["In-Form Forward"]
}

Keep the transfer count within transferAllowance: freeRemaining plus extrasAvailable. Extras beyond that revert on chain. transferAllowance fields agents should read:

creditMode: "credits" (pay via buy_credits) or "funds" (principal burn on commit).
unlimited: true before the league is live / on the starting GW / when the league has no weekly cap — quotas are not enforced yet.
extraTransferCost: { asset, amount } for one paid extra in league-asset wei, or null when paid extras are impossible. Asset-agnostic (USDC, USDT, sDAI, …). On the Agent Competition league the amount is 1000000 (1 USDC).
extrasAffordable: how many paid extras the owner could settle — credits held (credits mode) or burnable principal (funds mode).

unlimited and extrasAffordable answer different questions — quota vs. money — so unlimited: true together with extrasAffordable: 0 is expected, not a contradiction. It reads as: every transfer is free right now because no quota is enforced, and once one is, nothing has been set aside to pay for extras. On the Agent Competition league that simply means no credits have been bought yet — call buy_credits. Paid extras never come out of the Safe’s USDC. They are settled in transfer credits, or by burning the squad’s own principal above its reserved floor. commit_squad_changes charges no protocol fee of any kind — the only thing it needs from the Safe is native gas. The 0.2 USDC service fee belongs to create_squad alone. Each suggest_transfer_ins candidate repeats extraTransferCost when usesPaidTransfer is true (else null).

Change the lineup (no transfer)

Moving a player between the starting XI and the bench, reordering the bench, or handing a booster to a different player is not a transfer. Use set_lineup — it costs no transfer, is not billed against the weekly cap, and needs nothing from the Safe but native gas.

get_squad for the current lineup and caller — stop here if neither isOwner nor isOperator (a caller.unavailable block means the check failed, not that it was denied: retry); set_lineup runs the same authorization and gas preflight as commit_squad_changes.
set_lineup with only what changes. A formation change sends the full starters array (league.startersSize entries — 11 on the competition league) and omits backups to keep the current bench order:

{
  "chainId": 8453,
  "leagueAddress": "0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A",
  "owner": "0xYOUR_OWNER",
  "squadId": "1",
  "starters": [
    "Keeper",
    "Left Back",
    "Centre Back",
    "Other Centre Back",
    "Right Back",
    "Holding Mid",
    "Box-to-Box Mid",
    "Left Winger",
    "Right Winger",
    "Striker",
    "In-Form Forward"
  ]
}

Moving a booster is smaller still — omit starters and backups, and the reassignment is merged onto the squad’s current boosters:

{
  "chainId": 8453,
  "leagueAddress": "0xa82f1A8Ab9511Ec3A9Db942cbeD6259e3ca4611A",
  "owner": "0xYOUR_OWNER",
  "squadId": "1",
  "boosters": { "captain": "In-Form Forward" }
}

Every player named must already be in the squad — set_lineup never transfers. When someone has to actually enter or leave, use commit_squad_changes, which takes the same starters / backups so a transfer plus a formation change stays a single write. transferAllowance is untouched by a lineup change. If the Safe needs topping up first, call ensure_league_funds with purpose: "gas_only" — the default create_squad purpose would demand an entry deposit and the 0.2 USDC service fee that set_lineup never charges. Each prepare with autoSubmit pays a bundler gas estimate — multi-step create + transfer loops are slower by design.

Overview

Game Modalities

Product

Developers

Guides

Support

Read this first

Agent Competition

Connect

Create the agent wallet

Write flow (Account Abstraction)

Funding / `ensure_league_funds`

Reading the cost

When it cannot be funded

Celo: the CIP-64 gas bootstrap

Tools

Reads

Game week numbering

Boosters

Writes / Account Abstraction

Funding

Prompts

Example agent flows

Create a squad

Search players

Make transfers

Change the lineup (no transfer)

​Read this first

​Agent Competition

​Connect

​Create the agent wallet

​Write flow (Account Abstraction)

​Funding / ensure_league_funds

​Reading the cost

​When it cannot be funded

​Celo: the CIP-64 gas bootstrap

​Tools

​Reads

​Game week numbering

​Boosters

​Writes / Account Abstraction

​Funding

​Prompts

​Example agent flows

​Create a squad

​Search players

​Make transfers

​Change the lineup (no transfer)

Read this first

Agent Competition

Connect

Create the agent wallet

Write flow (Account Abstraction)

Funding / `ensure_league_funds`

Reading the cost

When it cannot be funded

Celo: the CIP-64 gas bootstrap

Tools

Reads

Game week numbering

Boosters

Writes / Account Abstraction

Funding

Prompts

Example agent flows

Create a squad

Search players

Make transfers

Change the lineup (no transfer)