Quickstart

Make your first query in under 2 minutes.

1

Get your API key

All requests require an API key. See Authentication for details on how to obtain one.

2

Send your first query

Query wallet positions for a single protocol against https://api.definitiv.io/graphql:

cURL
curl -X POST https://api.definitiv.io/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "{
      walletPositions(inputs: [{
        protocol: \"morpho\",
        chainId: 1,
        walletAddress: \"0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6\"
      }]) {
        data {
          ... on MorphoWalletPositions {
            protocol walletAddress chainId
            vaultV2Positions { vaultName assetsUsd apy }
          }
        }
        errors { protocol error { code message retryable } }
      }
    }"
  }'
JavaScript
const response = await fetch("https://api.definitiv.io/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    query: `{
      walletPositions(inputs: [
        { protocol: "morpho", chainId: 1, walletAddress: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6" }
      ]) {
        data {
          ... on MorphoWalletPositions {
            protocol
            walletAddress
            chainId
            vaultV2Positions {
              vaultName
              assetsUsd
              apy
            }
          }
        }
        errors {
          protocol
          error { code message retryable }
        }
      }
    }`
  })
});

const result = await response.json();
console.log(result.data.walletPositions);
3

Read the response

The response contains a data array with successfully resolved positions and an errors array for any failures:

Response
{
  "data": {
    "walletPositions": {
      "data": [
        {
          "protocol": "morpho",
          "walletAddress": "0x742d35cc6634c0532925a3b8d4c9db96c4b4d8b6",
          "chainId": 1,
          "vaultV2Positions": [
            {
              "vaultName": "Morpho Blue USDC",
              "assetsUsd": 10250.0,
              "apy": 0.0685
            }
          ]
        }
      ],
      "errors": []
    }
  }
}

Each protocol returns a different type. Use GraphQL inline fragments (... on MorphoWalletPositions, ... on AaveWalletPositions, etc.) to select protocol-specific fields.

Warning
Rate limit: 100 requests per 60-second window. Maximum 5 inputs per request. Exceeding the limit returns HTTP 429.
Tip
Query multiple protocols in a single request by passing multiple inputs. See walletPositions for examples.