Veranta (formerly Avantis)

Category: Trading

Catalog providers: avantis (perps, onboarding, referrals, builder fees), avantis-vault (LP vault). veranta and veranta-vault are accepted wherever a request names a provider.

Veranta, formerly Avantis v2, runs perpetuals on Base 8453 in USDC. The trader is the managed agent_wallet. During onboarding, Thirdfy mints and stores a delegate key. After that, the delegate signs each order and Veranta relays it. Gas is sponsored.

Pass chainId 8453 on writes. Other chain IDs fail closed.

Networks

Action coverage

All 37 actions are live on Base 8453.

Retired: the market-maker order actions, which never placed an order (a coin-sized market order is Veranta's market-maker path), and claim_veranta_vault (the v2 vault has no claim).

Credential model

Onboarding and allowance

complete_veranta_onboarding runs whatever setup is still missing:

1. Mints the stored delegate.
2. Signs DelegateReq from the trader wallet.
3. Approves USDC to Veranta's TradingStorage.

The approval covers the larger of targetCollateralUsdc and the wallet balance, not a fixed $5. Spend limits count onboarding as a $1 setup write, because an approval moves no capital.

Every open spends allowance. An order above the remaining allowance is refused up front with AVANTIS_ALLOWANCE_TOO_LOW. To top it up, run complete_veranta_onboarding again with targetCollateralUsdc. Once the trader is ready, get_veranta_onboarding_plan lists the approval as an optional step (reason: allowance_top_up). It is required only below the setup minimum.

Orders

Side and size.

• side is long or short, not Hyperliquid's isBuy.
• collateralUsdc is in USDC; leverage is the plain multiplier (20 means 20x).
• A position must clear the pair's minimum size (minLevPosUsdc on get_veranta_markets): $100 on the main crypto pairs, $10 on some commodity pairs.

TP/SL at open.

• takeProfitPrice and stopLossPrice are USD prices, signed into the open, so the position is protected from the fill.
• For a long, the take-profit sits above entry and the stop below it; for a short, the reverse. A wrong-side price is refused (AVANTIS_TAKE_PROFIT_WRONG_SIDE / AVANTIS_STOP_LOSS_WRONG_SIDE).
• A stop may lose at most 80% of collateral at the order's leverage (AVANTIS_STOP_LOSS_BEYOND_CAP).
• A filled market order returns fill with pairIndex, tradeIndex, openPrice, leverage, takeProfitPrice, stopLossPrice and collateralUsdc.

Limit orders. Pass orderType: "limit" with limitPrice; TP/SL may be included. The order appears in get_veranta_open_orders, and cancel_veranta_perps_order removes it by pairIndex and orderIndex.

Closing.

• close_veranta_position without collateralToCloseUsdc closes the whole position.
• With collateralToCloseUsdc it closes part and leaves the rest open.
• The on-chain TP/SL close with the position, so there is nothing to cancel first.

Changing TP/SL.

• update_veranta_tp_sl moves the whole-position levels.
• With partialClosePercent it arms a partial trigger that closes that share of the position. The result carries its entityId, and passing that id as triggerId replaces the trigger.
• cancel_veranta_tp_sl with triggerId removes one partial trigger. Without one, it removes the stop and resets the take-profit to the pair's maximum-gain cap.

Coin-sized orders.

• place_veranta_coin_perps_order fixes the exposure in base-asset units (coinExposure: 0.5 means 0.5 ETH); the fill leverage floats between minLeverage and maxLeverage.
• increase_veranta_coin_position adds exposure. Each added slice must clear the pair minimum on its own.
• close_veranta_coin_position closes part (coinExposure) or all of it.

TWAP.

• place_veranta_twap_order splits an open into slices over runTimeSeconds. The run time must fall within the pair's TWAP range and be a whole multiple of its slice frequency, and each slice must clear the pair minimum. It takes maxLeverage and returns twapId.
• cancel_veranta_twap_order stops the remaining slices.
• close_veranta_twap_order closes an open position in slices, using pairIndex, tradeIndex and runTimeSeconds.

Upside pairs. _UPSIDE pairs (for example ETH_UPSIDE/USD) are profit-share markets: no opening fee, and a share of the profit on close. They take market orders only; a limit order is refused with AVANTIS_UPSIDE_MARKET_ONLY. Their leverage range is the pair's PnL range shown on get_veranta_markets.

Close-only pairs. get_veranta_markets marks close-only and delisted pairs (closeOnly, isPairListed). Opens on those pairs are refused.

Reads

• get_veranta_positions:
  • leverage is the plain multiplier;
  • unrealizedPnlUsd is net of the close fee (or the Upside profit share), rollover and funding, settled the way the contract settles it (pnlBasis: "net", with a pnlBreakdown);
  • raw keeps Veranta's fixed-point fields (prices and leverage at 1e10, USDC at 1e6).
• get_veranta_spread needs a size (coinSize10, or collateralUsdc with leverage) and returns spreadPercent. If Veranta cannot quote a spread, the read fails with AVANTIS_SPREAD_UNAVAILABLE_DO_NOT_TRADE; it never reports zero.
• get_veranta_markets includes minLeverage, maxLeverage, minLevPosUsdc, isOpen, closeOnly, isPairListed and isUpside for every pair.

LP vault

The v2 vault has one tranche (junior).

• deposit_veranta_vault approves the tranche first when its allowance is short.
• request_veranta_vault_withdrawal withdraws USDC right away. It is limited to the live headroom less the vault's withdrawal fee (about 1.5%); an amount above that is refused before anything is sent (AVANTIS_VAULT_WITHDRAW_ABOVE_MAX).
• redeem_veranta_vault redeems a number of shares. get_veranta_vault_position shows shares, maxWithdraw and maxRedeem.

Referrals and builder fee

• Trader wallet only. Referral, vault and builder-fee writes are sent by the trader wallet itself. A traderAddress naming a different wallet is refused (AVANTIS_TRADER_NOT_CALLER).
• Builder fee. approve_veranta_builder_fee approves USDC to Veranta's builder-fee registry, and only once Thirdfy's builder code is registered there. Until then it is refused with AVANTIS_BUILDER_CODE_NOT_REGISTERED. revoke_veranta_builder_fee sets that approval to zero.

Write outcomes

• Confirmed. A write reports success only once Veranta or the chain confirms it.
• Unknown. If the result cannot be confirmed (a relayer or stream timeout), the write returns WRITE_OUTCOME_UNKNOWN with nextAction: reread_state_before_retry. Re-read positions or open orders before sending it again.
• Reverted. A reverted transaction returns TRANSACTION_REVERTED.
• Venue refusal. A refusal returns the Veranta reason, for example AVANTIS_ORDER_FAILED: ... BelowMinPosition().

Discovery

curl "https://api.thirdfy.com/api/v1/agent/actions/catalog"
thirdfy-agent actions --provider avantis --json

Reads

thirdfy-agent run --action get_veranta_markets --provider avantis --run-mode agent_wallet --chain-id 8453 --json
thirdfy-agent run --action get_veranta_setup_status --provider avantis --run-mode agent_wallet --chain-id 8453 --json
thirdfy-agent run --action get_veranta_positions --provider avantis --run-mode agent_wallet --chain-id 8453 --json

For agent_wallet setup and status reads, the CLI fills a missing traderAddress from that wallet.

Onboarding

thirdfy-agent run --action get_veranta_onboarding_plan --provider avantis --run-mode agent_wallet --chain-id 8453 --json
thirdfy-agent run --action complete_veranta_onboarding --params '{"targetCollateralUsdc":25,"confirmWrites":true}' --provider avantis --run-mode agent_wallet --chain-id 8453 --json

Place, protect and close

thirdfy-agent run --action place_veranta_perps_order --params '{"pairIndex":0,"side":"long","orderType":"market","collateralUsdc":10,"leverage":10,"takeProfitPrice":2800,"stopLossPrice":2550,"confirmWrites":true}' --provider avantis --run-mode agent_wallet --chain-id 8453 --json
thirdfy-agent run --action close_veranta_position --params '{"pairIndex":0,"tradeIndex":0,"confirmWrites":true}' --provider avantis --run-mode agent_wallet --chain-id 8453 --json

Writes take confirmWrites: true and an estimatedAmountUsd (the order notional). Confirm before any onboarding or trade write.

Execution lanes

MCP sequence (summary)

1. getProviderActions { provider: "avantis" }
2. get_veranta_funding_status and market reads (get_veranta_markets, get_veranta_spread with a size)
3. complete_veranta_onboarding on Base when setup is incomplete. get_veranta_onboarding_plan and prepare_veranta_onboarding preview it.
4. get_veranta_setup_status before live writes
5. place_veranta_perps_order with takeProfitPrice / stopLossPrice, then manage it with update_veranta_tp_sl or close with close_veranta_position

See Thirdfy MCP for the full recommended sequence.

Readiness checklist

• Set chainId to 8453. Other chain IDs fail closed.
• Fund Base USDC in the execution wallet.
• Complete onboarding so the stored delegate exists, delegation is on-chain, and the USDC allowance covers your orders.
• Check the pair on get_veranta_markets: open, not close-only, and your size above minLevPosUsdc.
• Re-run get_veranta_setup_status before the first live order.
• Confirm before any onboarding or trade write.

Console Command

Ask in Command to list Veranta markets, complete Base onboarding, or open a position with a stop and take-profit and close it. The operator uses the trading tool pack, sets Base, and confirms before a write.

Related

• Trading integrations
• Venue matrix
• Hyperliquid
• Lighter
• Supported chains
• Veranta SDK docs
• MCP discovery
• Execute Intent API
• Delegation and protection