> ## 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 a signable open intent targeting a fixed base-asset exposure > Gasless equivalent of /v2/trade/open-coin: the fill targets an exact base-asset exposure with leverage floating within [minLeverage, maxLeverage]. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution. ## OpenAPI ````yaml https://tx-builder-testnet.avantisfi.com/openapi.json post /v2/intents/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/intents/open-coin: post: tags: - intents summary: Build a signable open intent targeting a fixed base-asset exposure description: >- Gasless equivalent of /v2/trade/open-coin: the fill targets an exact base-asset exposure with leverage floating within [minLeverage, maxLeverage]. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution. operationId: postV2IntentsOpenCoin 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). nonce: anyOf: - type: string - type: number description: >- Replay-protection nonce (uint256; unordered Permit2-style bitmap, not sequential). A random one is generated when omitted — only pass a value to pre-reserve or deterministically retry an intent. Check availability via GET /v2/nonce. deadlineMs: anyOf: - type: string - type: number description: >- Intent expiry as a unix timestamp in MILLISECONDS (not seconds). Defaults to now + the service value shown in /v2/meta → defaults.intentDeadlineMs. trader: type: string description: >- The trader (position owner). USDC collateral is pulled from and paid out to this address. 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). 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. 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. 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: >- A ready-to-sign EIP-712 payload. Sign `{domain, types, primaryType, message}` with `signTypedData` (trader or a registered delegate, per `signerRule`) and hand the 65-byte r||s||v signature to the Avantis service that executes this intent kind. properties: intent: type: string description: >- The intent kind. Always `OpenTradeCoinExposureReq` for this endpoint. enum: - OpenTradeCoinExposureReq signerRule: type: string description: >- Who may sign: `trader-or-delegate` for most intents, `trader-only` where a delegate must not act (e.g. delegate registration). enum: - trader-only - trader-or-delegate domain: type: object description: >- EIP-712 signing domain. `verifyingContract` is the TradingRouter proxy for trading intents and the Referral contract for referral intents (which also has its own nonce space). properties: name: type: string description: Domain name. enum: - AvantisTrading version: type: string description: Domain version. enum: - '1' chainId: type: integer description: Chain id the signature is valid on. verifyingContract: type: string description: Contract that verifies the signature. example: '0x0000000000000000000000000000000000000000' required: - name - version - chainId - verifyingContract primaryType: type: string description: Same as `intent`; pass to `signTypedData`. enum: - OpenTradeCoinExposureReq types: type: object description: >- EIP-712 type definitions keyed by struct name; pass to `signTypedData` unchanged. properties: {} additionalProperties: true message: type: object description: >- The struct to sign. Field names mirror the on-chain Solidity structs verbatim (see the glossary in GET /v2/meta); all uint values are decimal strings. Pass `domain` / `types` / `primaryType` / `message` to `signTypedData` unchanged. properties: _t: type: object description: The Trade struct being opened. properties: trader: type: string description: The trader (position owner). example: '0x0000000000000000000000000000000000000000' pairIndex: type: string description: >- Pair index (see GET /v2/pairs). Decimal string (JSON-safe uint). index: type: string description: >- Per-pair trade slot index (0 on opens; assigned on-chain). Decimal string (JSON-safe uint). initialPosToken: type: string description: >- Always 0 on opens. On increases: the additional collateral being added, USDC 1e6. Decimal string (JSON-safe uint). positionSizeUSDC: type: string description: >- The trade's collateral in USDC 1e6. Misleading on-chain name — NOT the leveraged position size. Decimal string (JSON-safe uint). openPrice: type: string description: >- Reference/open price, 1e10-scaled. Decimal string (JSON-safe uint). buy: type: boolean description: '`true` = long, `false` = short.' leverage: type: string description: >- Leverage, 1e10-scaled. Decimal string (JSON-safe uint). tp: type: string description: >- Take-profit price, 1e10-scaled; 0 = not set. Decimal string (JSON-safe uint). sl: type: string description: >- Stop-loss price, 1e10-scaled; 0 = not set. Decimal string (JSON-safe uint). timestamp: type: string description: >- In Trade: set by the contract, 0 in requests. In TpSlReq: the position's open timestamp (binds the intent to the exact position instance). Decimal string (JSON-safe uint). required: - trader - pairIndex - index - initialPosToken - positionSizeUSDC - openPrice - buy - leverage - tp - sl - timestamp _type: type: string description: >- Order-type enum code (see `enums.openOrderType` in GET /v2/meta). Decimal string (JSON-safe uint). _coinExposure: type: string description: >- Exposure in base-asset units, 1e10-scaled (request param `coinExposure`). Decimal string (JSON-safe uint). _minLeverage: type: string description: >- Lowest fill leverage accepted, 1e10-scaled. Decimal string (JSON-safe uint). _maxLeverage: type: string description: >- Highest fill leverage accepted, 1e10-scaled. Decimal string (JSON-safe uint). _slippageP: type: string description: >- Max slippage percent, 1e10-scaled (1e10 = 1%). Decimal string (JSON-safe uint). _deadline: type: string description: >- Intent expiry in unix MILLISECONDS (the contract checks `deadline / 1000 >= block.timestamp`). Decimal string (JSON-safe uint). _nonce: type: string description: >- Signer-chosen 256-bit nonce on a Permit2-style unordered bitmap — any unused value works, no sequencing. Decimal string (JSON-safe uint). required: - _t - _type - _coinExposure - _minLeverage - _maxLeverage - _slippageP - _deadline - _nonce digest: type: string description: >- The EIP-712 typed-data hash. Recompute it locally and compare before signing — a mismatch means your signer would produce an invalid signature. encodedIntent: type: string description: >- The abi.encode of the struct — the `userIntent` bytes the Avantis operator entry point consumes. Useful for self-submission or debugging. meta: type: object description: >- Echo of the resolved request (pair resolution, live prices, validation). Informational only — not part of what is signed. properties: pair: type: string description: Resolved pair symbol, e.g. `ETH/USD`. pairIndex: type: integer description: Resolved pair index. openPrice: type: number description: >- Reference price used, USD — the live feed price when the request omitted it. 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 required: - intent - signerRule - domain - primaryType - types - message - digest - encodedIntent '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. ````