Quickstart

Make your first Yield API, Borrow API, or Perps API call: authenticate, discover, request an action, sign, submit, and track.

Each yield.xyz API follows the same loop: discover what’s available, request an action, sign the returned transactions yourself, submit them, and track the result. Pick the API you’re integrating.

Yield API

Earn: staking, DeFi, RWA, and stablecoin yield.

Borrow API

Supply collateral and borrow from lending markets.

Perps API

Open and manage perpetual futures positions.

We construct. You sign. Every action returns unsigned transactions; yield.xyz never holds keys or funds.

Before you start

Create a project and an API key in the dashboard, then send the key on every request in the x-api-key header. See Projects & API keys for how keys map to projects, and Onboarding for the full account setup.

API	Base URL
Yield API	https://api.yield.xyz/v1
Borrow API	https://borrow.yield.xyz/v1
Perps API	https://perps.yield.xyz/v1

Yield API

Enable the yields you want to offer in the dashboard first: GET /v1/yields returns only the yields enabled for your project.

1. Discover a yield

   List the yields enabled for your project and filter them, for example by network, token, provider, or yield type, with GET /v1/yields. Each result includes an id you use in every later call.

   cURL

   curl --request GET \
     --url 'https://api.yield.xyz/v1/yields?network=ethereum&limit=10' \
     --header "x-api-key: $YIELD_API_KEY"
   

   See Discover for the full set of filters.

2. Inspect the yield's required arguments

   Fetch the yield with GET /v1/yields/{yieldId} to read its mechanics.arguments.enter.fields, the schema-driven list of inputs the enter action needs. ethereum-eth-lido-staking, for example, requires only an amount:

   cURL

   curl --request GET \
     --url https://api.yield.xyz/v1/yields/ethereum-eth-lido-staking \
     --header "x-api-key: $YIELD_API_KEY"
   

   Response (truncated)

   {
     "id": "ethereum-eth-lido-staking",
     "mechanics": {
       "arguments": {
         "enter": {
           "fields": [
             { "name": "amount", "required": true }
           ]
         }
       }
     }
     // ...
   }
   

   Other yields add fields such as validatorAddress here. Always read the schema instead of hardcoding arguments; see Yield metadata.

3. Request the enter action

   Call POST /v1/actions/enter with the yieldId, the user’s address, and the arguments the schema required. The response is an action with an ordered transactions array, each holding an unsignedTransaction.

   cURL

   curl --request POST \
     --url https://api.yield.xyz/v1/actions/enter \
     --header "x-api-key: $YIELD_API_KEY" \
     --header 'content-type: application/json' \
     --data '{
       "yieldId": "ethereum-eth-lido-staking",
       "address": "0xYOUR_WALLET_ADDRESS",
       "arguments": { "amount": "0.1" }
     }'
   

   See Actions for the full action and status model.

4. Sign, submit, and track

   Execute action.transactions in order. Route each unsignedTransaction to your own signer (EOA, smart account, MPC, or institutional custody), then broadcast it. Once you have a transaction hash, report it with PUT /v1/transactions/{transactionId}/submit-hash so yield.xyz can track confirmation:

   cURL

   curl --request PUT \
     --url https://api.yield.xyz/v1/transactions/$TRANSACTION_ID/submit-hash \
     --header "x-api-key: $YIELD_API_KEY" \
     --header 'content-type: application/json' \
     --data '{ "hash": "0xYOUR_TRANSACTION_HASH" }'
   

   The action’s status moves from CREATED toward SUCCESS (or FAILED) as each transaction confirms.

5. Check the resulting balance

   Fetch the position with POST /v1/yields/{yieldId}/balances. Balances are lifecycle-aware (active, entering, exiting, withdrawable, claimable, locked) and can include pendingActions, such as CLAIM_REWARDS, that you pass into POST /v1/actions/manage to continue the position.

   cURL

   curl --request POST \
     --url https://api.yield.xyz/v1/yields/ethereum-eth-lido-staking/balances \
     --header "x-api-key: $YIELD_API_KEY" \
     --header 'content-type: application/json' \
     --data '{ "address": "0xYOUR_WALLET_ADDRESS" }'
   

   See Balances and positions for the full lifecycle and how to act on pendingActions.

Borrow API

1. Find a market

   List lending markets with GET /v1/markets, filtered by network or integrationId. Each market has an id and the integrationId of the protocol behind it.

   cURL

   curl --request GET \
     --url 'https://borrow.yield.xyz/v1/markets?network=base&limit=10' \
     --header "x-api-key: $YIELD_API_KEY"
   
2. Request an action

   Call POST /v1/actions with the market’s integrationId, the action, the user’s address, and args containing the marketId, the amount and, on pool markets such as Aave and SparkLend, the asset’s tokenAddress. Actions are supply, borrow, repay, withdraw, and, on pool markets only, enableCollateral and disableCollateral; on Morpho Blue (Ethereum and Base), supplyAndBorrow is also available when your project has a BlueBundle fee configuration.

   cURL

   curl --request POST \
     --url https://borrow.yield.xyz/v1/actions \
     --header "x-api-key: $YIELD_API_KEY" \
     --header 'content-type: application/json' \
     --data '{
       "integrationId": "YOUR_INTEGRATION_ID",
       "action": "supply",
       "address": "0xYOUR_WALLET_ADDRESS",
       "args": { "marketId": "YOUR_MARKET_ID", "amount": "100" }
     }'
   

   The response is an action whose transactions each carry a signingFormat and a signablePayload.

3. Sign and submit

   Sign each transaction in order. Then call POST /v1/transactions/{transactionId}/submit with either signedPayload (yield.xyz broadcasts it) or transactionHash (you already broadcast it):

   cURL

   curl --request POST \
     --url https://borrow.yield.xyz/v1/transactions/$TRANSACTION_ID/submit \
     --header "x-api-key: $YIELD_API_KEY" \
     --header 'content-type: application/json' \
     --data '{ "transactionHash": "0xYOUR_TRANSACTION_HASH" }'
   

   If the action returns hasNextStep: true, call POST /v1/actions/{id}/step after confirmation to get the next transactions.

4. Check the position

   Read the position with GET /v1/positions, passing integrationId, network, and address.

   cURL

   curl --request GET \
     --url 'https://borrow.yield.xyz/v1/positions?integrationId=YOUR_INTEGRATION_ID&network=base&address=0xYOUR_WALLET_ADDRESS' \
     --header "x-api-key: $YIELD_API_KEY"
   

See Borrow for markets, positions, and monetization.

Perps API

1. Find a market

   List markets with GET /v1/markets, filtered by providerId. Each market returns its id, leverage range, fees, funding rate, and minimum size.

   cURL

   curl --request GET \
     --url 'https://perps.yield.xyz/v1/markets?providerId=hyperliquid&limit=10' \
     --header "x-api-key: $YIELD_API_KEY"
   
2. Open a position

   Call POST /v1/actions with providerId, the user’s address, action: "open", and args: the marketId, a side (long or short), an amount (margin in USD) or a size (position size in USD), and a leverage; the position notional (size, or amount times leverage) must be at least 10 USD. If the account has no margin on the venue, deposit it first with the fund action.

   cURL

   curl --request POST \
     --url https://perps.yield.xyz/v1/actions \
     --header "x-api-key: $YIELD_API_KEY" \
     --header 'content-type: application/json' \
     --data '{
       "providerId": "hyperliquid",
       "address": "0xYOUR_WALLET_ADDRESS",
       "action": "open",
       "args": { "marketId": "YOUR_MARKET_ID", "side": "long", "amount": "100", "leverage": 5 }
     }'
   
3. Sign and submit

   Each returned transaction has a signingFormat, such as EIP712_TYPED_DATA, and a signablePayload. Sign the payload, then call POST /v1/transactions/{transactionId}/submit with the signedPayload; yield.xyz submits it to the venue.

   cURL

   curl --request POST \
     --url https://perps.yield.xyz/v1/transactions/$TRANSACTION_ID/submit \
     --header "x-api-key: $YIELD_API_KEY" \
     --header 'content-type: application/json' \
     --data '{ "signedPayload": "0xYOUR_SIGNATURE" }'
   
4. Check positions

   Read open positions with POST /v1/positions:

   cURL

   curl --request POST \
     --url https://perps.yield.xyz/v1/positions \
     --header "x-api-key: $YIELD_API_KEY" \
     --header 'content-type: application/json' \
     --data '{ "address": "0xYOUR_WALLET_ADDRESS", "providerId": "hyperliquid" }'
   

See Perps for action types, funding, and builder fees.

Next steps

Enter & exit flows

Build the full Yield API enter → sign → submit → track loop.

AI & Agents

Generate integration code or connect an agent through the MCP server.

Actions

Understand the enter, exit, and manage action model.

Yield API reference

Explore every endpoint, request, and response schema.