Execution, delegation, and tracking

Use execution tools to have your agent trade, deposit or place orders. Each write runs a catalog action, and Thirdfy refuses any action it doesn't support before anything is sent onchain.

Before your first write that needs a key, finish identity onboarding. If getVenueReadiness lists blockers, clear them with the venue onboarding tools.

Write rails

Pick the tool that matches how your agent holds funds:

Details:

• walletExecute answers directly. Read txHash, blockedReason and blockedStage from its response. Don't poll getIntentStatus for it.
• userDid is optional when agentKey is a 0x address. Thirdfy then uses did:wallet:<agentKey>. For an agent key that isn't an address, pass userDid yourself.
• Read responses put markets, bids, asks and readiness fields at the top level when present, so MCP hosts get a flatter shape.

Recommended write sequence

The usual order of calls for a write:

0. Onboarding (once): Onboarding tools
1. getActionsCatalog
2. getAgentActions
3. getProviderActions for the venue family
4. getChainCapabilities or getNonEvmCapabilities
5. Readiness gate
   • agent_wallet: agentWalletBootstrap with requireFundingCheck: true when collateral is required
   • self: getSelfReadiness then buildTx / walletSign
   • hybrid / thirdfy: delegationStatus and active Gator binding
6. Preview: previewOrder with the same action, params, estimatedAmountUsd and chainId
7. Write via the rail that matches runMode
8. Analytics: trackAgentAction and portfolio reads (see Tracking below)

Preview before you write

Call previewOrder to see what a write would do before it happens. It takes the same arguments as walletExecute and runs every check, but nothing is signed, billed or reserved.

It returns wouldSign, blockedReason, blockedStage and amountUsd. For a venue order (Veranta, Hyperliquid, Lighter, Polymarket) it also returns orderPreview:

• notional, collateral and leverage
• the remaining per-trade and daily limits
• one row per policy check

Veranta orders under an owner risk policy also show the liquidation price and the loss at stop. Lighter works with an agent key; it isn't offered in apps signed in with a Thirdfy account yet.

• Swaps and withdrawals: if Thirdfy can't size a value-moving write without an estimate, it answers ESTIMATED_AMOUNT_USD_REQUIRED. Pass estimatedAmountUsd.
• Order changes (move a TP or SL, close, cancel, margin): pass current with the position's values before the change. The preview shows before → after.
• Order cards: in hosts that support MCP Apps (Claude, ChatGPT, VS Code), the preview appears as an order card with a Place order button. The user places the order from the card, so the agent doesn't also send it with walletExecute.

Write confirmation

When you sign in with your Thirdfy account, the app acts with your authority as the owner. So a write that moves money pauses once and asks you to confirm. Nothing runs until you do:

• Hosts that support MCP forms show a confirmation form in the chat.
• Other hosts get errorCode: "CONFIRMATION_REQUIRED" (HTTP 428 over REST) and confirmation: { summary, confirmationToken, expiresAt, … }. Show the user the summary. If they agree, call again with the same arguments plus confirmationToken. The token is valid for 5 minutes.

The owner sets how often this happens with the agent's confirmationPolicy:

With an agent API key, writes run in one call. The agent's policy is the guard: its allowlist, per-trade and daily caps, and risk policy. Tools that use the owner's authority (delegationRedeem, delegationActivate, managedWalletGrant, consoleMandateActivate) still ask for confirmation every time. Reads never ask.

Solana

Solana runs only on walletExecute with chainId: 101 and runMode: agent_wallet.

• Call getNonEvmCapabilities for the chain IDs and providers.
• Call agentWalletBootstrap with chainId: 101 for the agent's Solana address (base58).
• buildTx, walletSign and walletSubmit work on EVM chains only.

See Solana.

Run mode quick reference

The run mode says who holds the authority to sign.

Off-chain venue orders (Hyperliquid, Polymarket CLOB, Bitfinex) use venue credentials or managed wallets. Don't use self for them.

Delegation and wallets

Three groups of tools set up who can sign:

• Delegation tools let a user grant the agent limited authority over their wallet (MetaMask Gator, the ERC-7710 standard). They serve the thirdfy and hybrid run modes.
• Managed wallet tools set up custodial delegation wallets.
• agentWalletBootstrap finds the agent's own execution wallet for agent_wallet.

Delegation tools

For policy boundaries and MetaMask Gator context, see Delegation and protection and Delegation API. World ID personhood is a separate flow: World ID delegation.

Managed wallet tools

Use these only when your product needs custodial delegation wallets for users. You don't need them for the default Hyperliquid or Polymarket agent wallet.

agentWalletBootstrap

Returns the agent's own execution wallet, the wallet Thirdfy manages for it (/api/v1/agent/execution-wallet, runMode=agent_wallet).

• Fund the returned execution wallet, not the wallet you sign in with.
• For Hyperliquid deposits through Bridge2, Bridge2 credits the address that sent the transaction on Arbitrum.
• When collateral is required, call it with requireFundingCheck: true before your first walletExecute.

For Hyperliquid and Polymarket, the agent signs through this managed execution wallet. Don't put venue private keys on your runtime.

Lane selection

Tracking and analytics

Tracking tools log what your agent did and read its results from Thirdfy. They do not get around execution policy.

Track tools

Execution still refuses any action outside the supported catalog. Tracking is deliberately looser, so agents can log what they intend to do before the catalog covers it.

Portfolio and leaderboard

MCP doesn't do portfolio math itself. The Thirdfy API computes principal, valuation snapshots and leaderboard scores.

Typical post-trade flow

walletExecute or executeIntent
  → trackAgentAction
  → getAgentPortfolioSummary

Workflow examples

For venue details, see the Integrations pages and the hints in getProviderActions.

Hosted runtime context

Hosted runtimes can pass executionContext (runtimeId, orgId) on walletExecute, executeIntent and agentRun. Thirdfy then charges credits to the right EarnOrg or Claude runtime.

Related

• Connect and authenticate
• Execute Intent API
• Agent CLI delegation
• Platform credits