Execute an action

Build the unsigned transactions for a Borrow action such as supply or borrow, and return them for the wallet to sign.

POST /v1/actions

Execute a borrow action

cURL

curl --request POST \
  --url https://borrow.yield.xyz/v1/actions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "integrationId": "aave-borrow",
  "action": "supply",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28",
  "args": {
    "marketId": "morpho-blue-borrow-base-cbbtc-usdc-86",
    "amount": "1.5",
    "amountRaw": "1500000",
    "repayAll": true,
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "collateralTokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "collateralAmount": "0.5",
    "collateralAmountRaw": "50000000",
    "borrowAmount": "100",
    "targetLtv": "0.1"
  }
}
'

201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "integrationId": "aave-borrow",
  "action": "supply",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28",
  "status": "CREATED",
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "network": "ethereum",
      "chainId": "1",
      "type": "SUPPLY",
      "status": "CREATED",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28",
      "signingFormat": "EVM_TRANSACTION",
      "signablePayload": "{\"from\":\"0x6877BB79...\",\"gasLimit\":\"350000\",\"to\":\"0xA238Dd80...\",\"data\":\"0x617ba037...\"}"
    }
  ],
  "hasNextStep": false,
  "currentStep": 1,
  "totalSteps": 1,
  "createdAt": "2023-11-07T05:31:56Z",
  "rawArguments": {
    "marketId": "morpho-blue-borrow-base-cbbtc-usdc-86",
    "amount": "1.5",
    "amountRaw": "1500000",
    "repayAll": true,
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "collateralTokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "collateralAmount": "0.5",
    "collateralAmountRaw": "50000000",
    "borrowAmount": "100",
    "targetLtv": "0.1"
  },
  "metadata": {
    "currentHealthFactor": "1.85",
    "predictedHealthFactor": "1.42",
    "currentLtv": "0.55",
    "predictedLtv": "0.72",
    "liquidationThreshold": "0.85",
    "predictedTotalSupplyUsd": "10000.00",
    "predictedTotalDebtUsd": "7200.00",
    "originationFeeBps": 100,
    "originationFeeAmount": "1.00",
    "effectivePrincipalAmount": "101.00",
    "feeAmount": "0.0005",
    "feeBps": 50,
    "effectiveCollateralAmount": "0.0125"
  }
}

Returns 201 with an action whose transactions[] you sign and submit in the order returned, using Submit a transaction, then poll Get an action. Nothing executes until a signed transaction is submitted. metadata previews the health factor and LTV after the action.

args is one flat object shared by every action. Required arguments per action and integration, the amount and amountRaw rules, repayAll, and the validation errors are in Action arguments. Which integration supports which action is in Availability by integration. The Borrow API applies no geolocation block on this route.

Only borrow and repay accept a collateral amount, which adds a collateral leg to the same action; see Collateral bundling. On pool markets it also needs collateralTokenAddress:

Borrow with collateral on a pool market

{
  "integrationId": "aave-borrow",
  "action": "borrow",
  "address": "0xYOUR_WALLET_ADDRESS",
  "args": {
    "marketId": "YOUR_MARKET_ID",
    "amount": "500",
    "collateralTokenAddress": "0xYOUR_COLLATERAL_TOKEN_ADDRESS",
    "collateralAmount": "0.5"
  }
}

Close a debt

{
  "integrationId": "aave-borrow",
  "action": "repay",
  "address": "0xYOUR_WALLET_ADDRESS",
  "args": { "marketId": "YOUR_MARKET_ID", "repayAll": true }
}

Errors return statusCode, timestamp, path and message. Common causes of 400: an unknown or unsupported integrationId, an action the integration does not support, an argument that fails the rules above, and Lista minLoan violations. An unknown marketId returns 404. See Errors and retries.

Authorizations

x-api-key · string · header · required

Body

application/json

integrationId · string · required

Integration identifier

Example:

"aave-borrow"

action · enum<string> · required

Action to execute

Available options: supply, borrow, repay, withdraw, enableCollateral, disableCollateral, supplyAndBorrow

Example:

"supply"

address · string · required

User wallet address

Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28"

args · object · required

Action arguments

Show child attributes

Response

201

application/json

Action created with unsigned transactions ready for signing

id · string · required

Unique action identifier (UUID)

Example:

"550e8400-e29b-41d4-a716-446655440000"

integrationId · string · required

Integration identifier

Example:

"aave-borrow"

action · enum<string> · required

Action type executed

Available options: supply, borrow, repay, withdraw, enableCollateral, disableCollateral, supplyAndBorrow

Example:

"supply"

address · string · required

User wallet address

Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28"

status · enum<string> · required

Current action status

Available options: CANCELED, CREATED, WAITING_FOR_NEXT, PROCESSING, FAILED, SUCCESS, STALE

Example:

"CREATED"

transactions · object[] · required

Transactions to sign (current step only)

Show child attributes

hasNextStep · boolean · required

Whether there are more transactions to sign after the current step completes. When true, call POST /actions/:id/step after confirming to get the next transaction(s). Used for async multi-step flows such as cross-chain bridges or delayed withdrawals.

Example:

false

currentStep · number · required

Current step number (1-indexed)

Example:

1

totalSteps · number · required

Total number of steps in this action. Most actions are single-step. Multi-step actions occur when an async operation (e.g., bridge confirmation) must complete before the next transaction can be constructed.

Example:

1

createdAt · string<date-time> · required

When the action was created

rawArguments · object

Raw arguments as submitted

Show child attributes

metadata · object

Action metadata with predicted position impact (health factor, LTV, USD totals)

Show child attributes