> ## Documentation Index > Fetch the complete documentation index at: https://sdk.avantisfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Build an open-position transaction targeting a fixed base-asset exposure > Like /v2/trade/open, but the fill targets an exact exposure in base-asset units (e.g. exactly 0.5 ETH) instead of a USD notional; the fill leverage floats within [minLeverage, maxLeverage]. Only market and market_pnl order types are supported. ## OpenAPI ````yaml https://tx-builder-testnet.avantisfi.com/openapi.json post /v2/trade/open-coin openapi: 3.0.3 info: title: Avantis v2 API version: 2.0.0 description: >- Calldata builders, EIP-712 intent builders, signed-tx relay, and on-chain reads for the Avantis v2 perp protocol. **Conventions** - Every build/read endpoint accepts both GET (query string) and POST (JSON body) with the same fields; POST /v2/relay is POST-only. - All amounts are human units: `collateralUsdc: 100` = 100 USDC, `leverage: 10` = 10x, prices are plain USD decimals. The API does all on-chain scaling. - Responses use the `{ ok: true, data }` / `{ ok: false, error: { code, message, details } }` envelope. - Calldata responses (`to`, `from`, `data`, `value`) are unsigned — the caller signs and broadcasts (or submits via POST /v2/relay). `from` is who must sign; `value` is hex wei. - Intent responses (`domain`, `types`, `primaryType`, `message`) feed directly into EIP-712 signTypedData; the Avantis operator executes them gas-free for the signer. - Trading endpoints are rate-limited per IP. Start with GET /v2/meta (addresses, enums, units, defaults) and GET /v2/pairs (market catalog). servers: - url: https://tx-builder-testnet.avantisfi.com security: [] tags: - name: meta description: Service metadata, pair catalog, health and metrics. - name: trading description: >- Build unsigned transactions for market/limit opens and closes, margin changes, and position increases (the direct, self-broadcast route). - name: delegate description: >- Authorize or revoke a delegate key that can trade on behalf of a trader (never move funds). - name: token description: >- USDC approval transactions — the one-time prerequisite before trading or LP deposits. - name: intents description: >- Build EIP-712 typed-data payloads to sign; the Avantis operator submits them on-chain so the signer pays no gas (the relayer route). - name: relay description: >- Submit an already-signed transaction through Avantis-operated RPCs: whitelist check, simulation with decoded revert reasons, then broadcast. - name: twap description: >- Time-weighted orders, filled in slices by the operator over a chosen duration. - name: referral description: >- Referral code registration, assignment, ownership transfer, and rebate claims. - name: lp description: >- Liquidity-provider flows on the Avantis USDC vault (ERC-4626 avUSDC tranche). - name: misc description: Keeper reward claims, vault buffer top-ups, and builder-code registration. - name: reads description: >- On-chain lookups the SDK needs for signing correctness: nonces, positions, delegation state, allowances. paths: /v2/trade/open-coin: post: tags: - trading summary: Build an open-position transaction targeting a fixed base-asset exposure description: >- Like /v2/trade/open, but the fill targets an exact exposure in base-asset units (e.g. exactly 0.5 ETH) instead of a USD notional; the fill leverage floats within [minLeverage, maxLeverage]. Only market and market_pnl order types are supported. operationId: postV2TradeOpenCoin requestBody: required: true content: application/json: schema: type: object properties: pairIndex: type: integer minimum: 0 description: Pair index (alternative to `pair`). pair: type: string minLength: 1 description: >- Pair symbol, e.g. ETH/USD (separators /, -, _ accepted; case-insensitive). trader: type: string description: >- The trader (position owner). USDC collateral is pulled from and paid out to this address. delegate: type: string description: >- Optional pre-authorized delegate. When set, the call is wrapped in delegatedAction(trader, …) and `from` becomes this address — the delegate signs the transaction and pays gas. Register one via /v2/delegate/set. side: type: string enum: - long - short description: 'Position direction: long or short.' orderType: type: string enum: - market - stop_limit - limit - market_pnl - market_zero_fee description: >- Open order type: market (immediate), limit / stop_limit (queued at openPrice), or market_pnl (zero-fee, profit-share on close). default: market collateralUsdc: anyOf: - type: string - type: number description: >- Collateral (margin) in USDC, human units — e.g. 100 = 100 USDC. Position size = collateral × leverage. leverage: anyOf: - type: string - type: number description: Leverage as a plain multiplier (10 = 10x). slippagePercent: anyOf: - type: string - type: number description: Max slippage in percent (1 = 1%). default: '1' openPrice: anyOf: - type: string - type: number description: >- Entry price in USD. Market orders: optional override, resolved from the live price feed when omitted. Limit / stop-limit orders: the trigger price (required). takeProfit: anyOf: - type: string - type: number description: >- Take-profit price in USD. 0 or omitted = no take-profit (0 also removes an existing one on updates). stopLoss: anyOf: - type: string - type: number description: >- Stop-loss price in USD. 0 or omitted = no stop-loss (0 also removes an existing one on updates). executionFeeWei: anyOf: - type: string - type: number description: >- ETH (wei) attached as msg.value and forwarded to the Avantis operator that fulfills the order. Defaults to the service value shown in /v2/meta → defaults.executionFeeWei. skipValidation: anyOf: - type: boolean - type: string default: false description: >- Skip server-side pre-trade validation (listing, min position, leverage bounds, liquidity, market hours) and just encode the call. The chain still enforces all limits. coinExposure: anyOf: - type: string - type: number description: >- Position exposure in base-asset units (e.g. 0.5 = 0.5 ETH on ETH/USD). minLeverage: anyOf: - type: string - type: number description: >- Lowest fill leverage you accept; defaults to the pair minimum. maxLeverage: anyOf: - type: string - type: number description: >- Highest fill leverage you accept; defaults to the pair maximum. required: - trader - side - collateralUsdc - leverage - coinExposure additionalProperties: false responses: '200': description: >- Success envelope: `ok` is `true` and `data` carries the payload documented below. content: application/json: schema: type: object required: - ok - data properties: ok: type: boolean enum: - true description: Always `true` on success. data: type: object description: >- An unsigned EVM transaction. Sign it with the `from` key and broadcast it yourself, or submit the signed bytes via POST /v2/relay. properties: to: type: string description: >- Contract to call (already resolved, e.g. the TradingRouter proxy). example: '0x0000000000000000000000000000000000000000' from: type: string description: >- The account that must sign and send this transaction — the trader, or the delegate when the call is wrapped in `delegatedAction`. example: '0x0000000000000000000000000000000000000000' data: type: string description: ABI-encoded calldata, 0x-prefixed hex. value: type: string description: >- Required `msg.value` in wei as 0x-prefixed hex (hex avoids JSON precision loss on big values). Non-zero when an operator execution fee must be attached — forward it verbatim. example: '0x0' chainId: type: integer description: Chain the transaction is valid on (EIP-155). description: type: string description: Human-readable summary of what this transaction does. meta: type: object description: >- Echo of the resolved request (pair resolution, live prices, fees). Informational only — not part of the transaction. properties: pair: type: string description: Resolved pair symbol, e.g. `ETH/USD`. pairIndex: type: integer description: Resolved pair index. delegated: type: boolean description: >- Whether the call was wrapped in `delegatedAction` (i.e. `delegate` was provided and `from` is the delegate). executionFeeWei: type: string description: >- Operator execution fee attached as `value`, in wei (decimal string). orderType: type: string description: Echo of the requested order type. isPnl: type: boolean description: '`true` for `market_pnl` (PnL-fee) orders.' isLong: type: boolean description: Position direction. collateralUsdc: type: string description: Echo of the collateral, human units. leverage: type: string description: Echo of the leverage. slippagePercent: type: string description: Echo of the max slippage percent. openPrice: type: number description: >- Reference price used, USD — the live feed price when the request omitted it. takeProfit: type: string description: Echo of the TP price; `null` if not set. nullable: true stopLoss: type: string description: Echo of the SL price; `null` if not set. nullable: true validation: type: object description: >- Pre-trade validation summary (the checks this build passed). `null` when `skipValidation=true`. properties: positionSizeUsdc: type: number description: >- Requested position size: `collateral × leverage`, USDC. pairAvailableUsdc: type: number description: >- Remaining pair open-interest headroom (`pairMaxOI − pairOI`), USDC. groupAvailableUsdc: type: number description: >- Remaining group open-interest headroom, USDC. `null` if group data was unavailable. nullable: true availableUsdc: type: number description: >- Effective liquidity bound: `min(pairAvailable, groupAvailable)`, USDC. minLeverage: type: number description: >- Lower leverage bound applied (the PnL envelope for `market_pnl` orders, the fixed-fee envelope otherwise). maxLeverage: type: number description: >- Upper leverage bound applied (same envelope selection). minPositionUsdc: type: number description: >- Minimum `collateral × leverage` allowed on this pair, USDC. isPnl: type: boolean description: >- `true` when the PnL-fee (`market_pnl`) leverage envelope was used. marketOpen: type: boolean description: >- Whether the market accepts immediate-execution orders right now. nextOpenSec: type: number description: >- Unix seconds of the next market open; `null` if the pair has no schedule (e.g. crypto). nullable: true nextCloseSec: type: number description: >- Unix seconds of the next market close; `null` if the pair has no schedule. nullable: true nullable: true coinExposure: type: string description: Echo of the fixed base-asset exposure target. minLeverage: type: string description: >- Lower fill-leverage bound applied (pair envelope when not supplied). maxLeverage: type: string description: >- Upper fill-leverage bound applied (pair envelope when not supplied). required: - to - from - data - value - chainId - description '400': description: >- Invalid input (failed schema validation or pre-trade checks like liquidity, leverage bounds, min position size, or market hours). content: application/json: schema: type: object required: - ok - error properties: ok: type: boolean enum: - false description: Always `false` on errors. error: type: object required: - code - message description: Machine-readable error. properties: code: type: string enum: - BAD_REQUEST description: Stable error code for programmatic handling. message: type: string description: Human-readable explanation of what went wrong. details: description: >- Optional structured context — e.g. Zod validation issues on BAD_REQUEST, or `{ target, revertData, decodedError }` on SIMULATION_FAILED. ````