Create a position (deploy a collateral vault)

GET /v1/actions/twyne/create-position

Deploy the borrower's collateral vault, choosing its liquidation LTV. This is the first step on Twyne — there is no "first deposit opens it" path, and the standard lending ops refuse an account that has no vault in the market.

Twyne is a credit-delegation layer over Aave V3 and Euler V2, not a lending market of its own: capital never leaves the external protocol. Credit-LPs deposit a receipt token they already hold (eWETH, or a Twyne wrapper around an aToken) into an intermediate credit vault; a borrower deploys a collateral vault — one contract per position — that RESERVES that credit, so the external market sees one ordinary borrower while the user's own collateral carries a much higher LTV (93.26 % → 98 %).

Three consequences shape this API:

A position is a contract, and there may be SEVERAL per user per market. Every op past the create takes an optional posId (the collateral vault address); omitted, it resolves the account's only vault and refuses when there is more than one. Discovery is factory.getCollateralVaults(borrower).
There is no per-market LTV. Each position carries its own twyneLiqLTV, chosen at deploy time inside a live BAND: extLiqLTV × externalLiqBuffer ≤ chosen ≤ maxTwyneLTVs. Both bounds move — governance ramps the ceiling, and for a PT market the floor drifts as the collateral ages — so they are read fresh on every call and returned as data.band.
The collateral is not all the borrower's. totalAssetsDepositedOrReserved − maxRelease() is what a withdraw can pay out; the rest is reserved Credit-LP capital.

Every borrower op is an evc.call through Twyne's OWN EVC 0xef39D649…, never Euler's canonical one. Liquidation is by INHERITANCE — the liquidator becomes the borrower and heals the position — so there is no seize-and-sell penalty auction.

liqLtv is validated against a LIVE band read and is refused above the ceiling, below the floor, or against collateral that has already MATURED (two of the three PT markets are expired — existing positions there stay actionable, new ones are not opened).

The vault's address is not returned: it is only knowable once the deploy has executed, which the response states as data.vaultAddressKnownAfterExecution. Read it from the T_CollateralVaultCreated event in the receipt, or from factory.getCollateralVaults(account) afterwards. A single batch that creates AND funds the position needs the address up front — that is evc.batchSimulation, not a pinned CREATE2 hash, because the hash is a property of the factory implementation and that has already changed four times.

Plain-text reference — GET /v1/actions/twyne/create-position

Parameters

Parameter	In	Type	Required	Description
`chainId`	query	string	yes	Chain id See the `ChainId` schema for the full set of supported chains.
`lender`	query	string	yes	Per-market key, e.g. TWYNE_1_<INTERMEDIATE_VAULT>_<TARGET_ASSET> See the `LenderId` schema for the full set of accepted values.
`operator`	query	string	yes	Borrower (tx sender)
`liqLtv`	query	string	yes	The position's liquidation LTV, 1e4 scale (e.g. 9500 = 95 %). Must sit inside the market's live band, returned as data.band

Response 200

Field	Type	Description
`success`	`True`
`data`	object	Informational data (quotes, simulation results, etc.)
`actions`	object	Transaction calldata and approvals. Null for quote-only responses (no account provided).
`actions.transactions`	object[]	Pre-trade setup transactions (e.g. e-mode switch, collateral enable). Execute these before the main swap. Empty when no setup is needed.
`actions.transactions[].to`	string	Target contract address
`actions.transactions[].data`	string	Encoded calldata
`actions.transactions[].value`	string	ETH value to send with the transaction
`actions.transactions[].description`	string	Human-readable label. For `alternatives`, this is the aggregator name (e.g. "Paraswap"). For `transactions`, describes the setup action (e.g. "Switch e-mode to 1").
`actions.alternatives`	object[]	DEX aggregator swap transactions sorted by best output (descending). Each entry's `description` is the aggregator name. The client should pick one to execute. Present on loop action endpoints.
`actions.alternatives[].to`	string	Target contract address
`actions.alternatives[].data`	string	Encoded calldata
`actions.alternatives[].value`	string	ETH value to send with the transaction
`actions.alternatives[].description`	string	Human-readable label. For `alternatives`, this is the aggregator name (e.g. "Paraswap"). For `transactions`, describes the setup action (e.g. "Switch e-mode to 1").
`actions.permissions`	object[]	Approval/delegation transactions that must execute before both `transactions` and `alternatives`. Includes ERC20 allowances (targeting the composer contract) and lender borrow/withdrawal delegations (targeting the lending protocol contract directly). Filtered against on-chain state so only missing approvals are returned. Null when no approvals are needed.
`actions.permissions[].to`	string	Target contract address
`actions.permissions[].data`	string	Encoded calldata
`actions.permissions[].value`	string	ETH value
`actions.permissions[].description`	string	Human-readable description of the approval (e.g. "Approve borrow for AAVE_V3", "Approve ERC20")
`actions.permissions[].spender`	string	ERC-20 approve spender (x-chain permissions). Match it against the selected quote's `approvalTarget` — several bridges can share one spender, so do not match by description.

Example response

{
  "success": true,
  "data": {},
  "actions": {
    "transactions": [
      {
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "alternatives": [
      {
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "permissions": [
      {
        "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      }
    ]
  }
}

Request

Responses

Create-position transaction + the validated band

Rate limited. Unauthenticated callers share a per-IP budget; send an x-api-key header to lift it. Retry with exponential backoff.

An upstream data source or protocol origin failed (error.code is ORIGIN_FAILED). error.details carries the per-origin status. This is also what a missing or malformed required parameter currently returns, rather than a 400.

Create a position (deploy a collateral vault)

/v1/actions/twyne/create-position

Request​

Responses​

Request

Responses