Getting Started

Making your first API request

Step Finance provides a REST API for accessing portfolio data on the Solana blockchain. Access to the API requires a valid API key which can be generated after purchasing a plan on our website. For more info on plans see Purchasing.

Example Request with API Key

const API_KEY = "<your-api-key>";
const WALLET_ADDRESS = "<wallet-address>";
const API_URL = `https://api.step.finance/v1/portfolio/all/${WALLET_ADDRESS}?apiKey=${API_KEY}`;

async function fetchPortfolioData() {
  const response = await fetch(API_URL, {
    method: "GET",
    headers: {
      "Content-Type": "application/json"
    }
  });

  if (!response.ok) {
    throw new Error(`Error: ${response.statusText}`);
  }

  const data = await response.json();
  console.log(data);
}

fetchPortfolioData().catch(console.error);

Filtering Data by Module

User portfolio data is grouped into one of several modules. some of which have subgroups. A single module or subgroup will contain positions fetched from a number DeFi providers. For more details on various modules and credit costs see Credit Usage.

Desired modules can be selected using the modules and/or excludeModules query params.

Example: Fetching Specific Modules

const MODULES = "token,farm,liquidity";
const FILTERED_API_URL = `${API_URL}&modules=${MODULES}`;

async function fetchSelectedModules() {
  const response = await fetch(FILTERED_API_URL, {
    method: "GET",
    headers: {
      "Content-Type": "application/json"
    }
  });

  if (!response.ok) {
    throw new Error(`Error: ${response.statusText}`);
  }

  const data = await response.json();
  console.log(data);
}

fetchSelectedModules().catch(console.error);

Understanding How Data Fetching Works

To get the most out of our API, it’s helpful to understand how data is retrieved and cached.

Data Retrieval and Caching

• When a request is made to the Portfolio API, it immediately returns any cached data available for the requested wallet.

• The very first time a wallet is fetched, the response will contain empty positions, and the overall status will be marked as stale.

• Each integration (e.g., Raydium Staking) tracks its own staleness, ensuring freshness is managed individually.

• Retrieved data is cached and remains fresh until the configured staleTime is reached.

• The staleTime can be adjusted via query parameters, with a minimum of 15 seconds and a default of 60 seconds.

Example Initial Stale Response

{
  "wallet": "8NoTrLoMnvBi2EMQGPcMKonR8G2f5LEEaBTw1xy8VwQi",
  "positions": {
    "token": {
      "spot": [],
      "yield": []
    },
    ...
  },
  "summary": {
    "positions": {
      "token": {
      ...
    },
    "staleJobs": [
      "token.balances",
      ...
    ]
  },
  "status": "stale"
}

Refreshing Data and Stale Jobs

• Outstanding jobs with stale data can be found under the staleJobs key in the response.

• Each request triggers the API to retrieve fresh data for any stale integrations and cache it.

• On subsequent requests, any fresh data retrieved in the meantime will be immediately visible.

• Credits are not deducted for a request until all returned data is marked as fresh.

{
  "wallet": "8NoTrLoMnvBi2EMQGPcMKonR8G2f5LEEaBTw1xy8VwQi",
  "positions": {
    "token": {
      "spot": [
        {
          "asset": {
            "title": "USD Coin",
            ...
          },
          "balance": 5.367675,
          ...
        },
      ],
    },
    ...
  },
  "summary": {
    "positions": {
      "token": {
      ...
    },
    "staleJobs": []
  },
  "status": "ok"
}

Waiting for Fresh Data in a Single Request

To wait for fresh data before receiving a response, set the maxWaitTime query parameter:

• The API will wait until all data is refreshed or the maxWaitTime is reached before responding.

• If fresh data retrieval is incomplete within the maxWaitTime, fetching and caching still continues on the API. A second request after a short interval may be all you need to retrieve the remaining fresh data.

Example: Waiting for Fresh Data Before Response

const WAIT_TIME = 30; // Wait up to 30 seconds for fresh data
const WAIT_API_URL = `${API_URL}&maxWaitTime=${WAIT_TIME}`;

async function fetchWithWait() {
  const response = await fetch(WAIT_API_URL, {
    method: "GET",
    headers: {
      "Content-Type": "application/json"
    }
  });

  if (!response.ok) {
    throw new Error(`Error: ${response.statusText}`);
  }

  const data = await response.json();
  console.log(data);
}

fetchWithWait().catch(console.error);

Best Practices

• If you want data quickly, and your UI can benefit from incremental data becoming available, poll the API every few seconds and update your UI with what is available until the response status is "ok".

• Use maxWaitTime for one-time requests that wait for fresh data.

• Fetch only necessary modules to reduce response size and improve efficiency.