> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Columns cols={3}>
  <Card title="Yield API" icon="chart-line" href="#yield-api">
    Earn: staking, DeFi, RWA, and stablecoin yield.
  </Card>

  <Card title="Borrow API" icon="hand-holding-dollar" href="#borrow-api">
    Supply collateral and borrow from lending markets.
  </Card>

  <Card title="Perps API" icon="arrow-right-arrow-left" href="#perps-api">
    Open and manage perpetual futures positions.
  </Card>
</Columns>

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

## Before you start

Create a project and an API key in the [dashboard](https://dashboard.yield.xyz), then send the key on every request in the `x-api-key` header. See [Projects & API keys](/documentation/get-started/projects-api-keys) for how keys map to projects, and [Onboarding](/documentation/get-started/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.

<Steps>
  <Step title="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`](/api-reference/YieldsController_getYields). Each result includes an `id` you use in every later call.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url 'https://api.yield.xyz/v1/yields?network=ethereum&limit=10' \
        --header "x-api-key: $YIELD_API_KEY"
      ```

      ```typescript TypeScript theme={null}
      const res = await fetch(
        'https://api.yield.xyz/v1/yields?network=ethereum&limit=10',
        { headers: { 'x-api-key': process.env.YIELD_API_KEY! } },
      );
      const { items } = await res.json();
      ```
    </CodeGroup>

    See [Discover](/documentation/earn/core-concepts/discover) for the full set of filters.
  </Step>

  <Step title="Inspect the yield's required arguments">
    Fetch the yield with [`GET /v1/yields/{yieldId}`](/api-reference/YieldsController_getYield) 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`:

    ```bash cURL theme={null}
    curl --request GET \
      --url https://api.yield.xyz/v1/yields/ethereum-eth-lido-staking \
      --header "x-api-key: $YIELD_API_KEY"
    ```

    ```json Response (truncated) theme={null}
    {
      "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](/documentation/earn/core-concepts/yield-metadata).
  </Step>

  <Step title="Request the enter action">
    Call [`POST /v1/actions/enter`](/api-reference/ActionsController_enterYield) 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`.

    <CodeGroup>
      ```bash cURL theme={null}
      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" }
        }'
      ```

      ```typescript TypeScript theme={null}
      const res = await fetch('https://api.yield.xyz/v1/actions/enter', {
        method: 'POST',
        headers: {
          'x-api-key': process.env.YIELD_API_KEY!,
          'content-type': 'application/json',
        },
        body: JSON.stringify({
          yieldId: 'ethereum-eth-lido-staking',
          address: '0xYOUR_WALLET_ADDRESS',
          arguments: { amount: '0.1' },
        }),
      });
      const action = await res.json();
      // action.transactions: ordered, unsigned transactions to sign and broadcast
      ```
    </CodeGroup>

    See [Actions](/documentation/earn/core-concepts/actions) for the full action and status model.
  </Step>

  <Step title="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`](/api-reference/TransactionsController_submitTransactionHash) so yield.xyz can track confirmation:

    ```bash cURL theme={null}
    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.
  </Step>

  <Step title="Check the resulting balance">
    Fetch the position with [`POST /v1/yields/{yieldId}/balances`](/api-reference/YieldsController_getYieldBalances). 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.

    ```bash cURL theme={null}
    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](/documentation/earn/core-concepts/balances-positions) for the full lifecycle and how to act on `pendingActions`.
  </Step>
</Steps>

## Borrow API

<Steps>
  <Step title="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.

    ```bash cURL theme={null}
    curl --request GET \
      --url 'https://borrow.yield.xyz/v1/markets?network=base&limit=10' \
      --header "x-api-key: $YIELD_API_KEY"
    ```
  </Step>

  <Step title="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.

    ```bash cURL theme={null}
    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`.
  </Step>

  <Step title="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):

    ```bash cURL theme={null}
    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.
  </Step>

  <Step title="Check the position">
    Read the position with `GET /v1/positions`, passing `integrationId`, `network`, and `address`.

    ```bash cURL theme={null}
    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"
    ```
  </Step>
</Steps>

See [Borrow](/documentation/borrow/index) for markets, positions, and monetization.

## Perps API

<Steps>
  <Step title="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.

    ```bash cURL theme={null}
    curl --request GET \
      --url 'https://perps.yield.xyz/v1/markets?providerId=hyperliquid&limit=10' \
      --header "x-api-key: $YIELD_API_KEY"
    ```
  </Step>

  <Step title="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.

    ```bash cURL theme={null}
    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 }
      }'
    ```
  </Step>

  <Step title="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.

    ```bash cURL theme={null}
    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" }'
    ```
  </Step>

  <Step title="Check positions">
    Read open positions with `POST /v1/positions`:

    ```bash cURL theme={null}
    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" }'
    ```
  </Step>
</Steps>

See [Perps](/documentation/trade/perps) for action types, funding, and builder fees.

## Next steps

<Columns cols={2}>
  <Card title="Enter & exit flows" icon="arrow-right-arrow-left" href="/guides/earn/enter-exit-flows">
    Build the full Yield API enter → sign → submit → track loop.
  </Card>

  <Card title="AI & Agents" icon="robot" href="/documentation/ai-agents/index">
    Generate integration code or connect an agent through the MCP server.
  </Card>

  <Card title="Actions" icon="bolt" href="/documentation/earn/core-concepts/actions">
    Understand the enter, exit, and manage action model.
  </Card>

  <Card title="Yield API reference" icon="code" href="/api-reference/getting-started">
    Explore every endpoint, request, and response schema.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.