Getting started with the Royco API

1. Get Your API Key

• For Production: Contact the Royco team on telegram at https://t.me/royco_support_bot to receive your API key

• For Testing: Use the demo key ROYCO_DEMO

2. Access the API Documentation

Visit our interactive API documentation at api.royco.org for a overview on the endpoints available.

3. Authenticate

1. Click the "Authorize" button (top-right corner)

2. Enter your API key in the x-api-key field

3. Click "Authorize"

4. Close the modal

API Overview

Base URL

https://api.royco.org

Authentication

All API requests require authentication via one of these methods:

• Header: x-api-key: YOUR_API_KEY

• Query Parameter: ?apiKey=YOUR_API_KEY

Core Concepts

Market Types

• Recipe Markets (Type 0): Automated yield strategies

• Vault Markets (Type 1): Lending protocols

Global Market ID

Each market has a unique identifier in the format:

{chainId}_{marketType}_{marketId}

Example:

• URL: https://app.royco.org/market/1/0/0x83c459782b2ff36629401b1a592354fc085f29ae00cf97b803f73cac464d389b

• Global ID: 1_0_0x83c459782b2ff36629401b1a592354fc085f29ae00cf97b803f73cac464d389b

Popular Endpoints

Markets

• Get Market Info: POST /api/v1/market/info/{id}

• Get all Markets: POST /api/v1/market/explore

Positions

• Recipe Positions: POST /api/v1/position/recipe

• Vault Positions: POST /api/v1/position/vault

• Global Positions: POST /api/v1/position/global/{accountAddress}

Offers

• Recipe Offers: POST /api/v1/offer/recipe

• Vault Offers: POST /api/v1/offer/vault

Your First API Call

Let's fetch markets on Ethereum mainnet, by 10 per page.

1. Select the Endpoint

• Go to POST api/v1/market/explore in the API docs

2. Add Filters

{
  "filters": [
    {
      "id": "chainId",
      "value": 1
    }
  ],
  "page": {
    "index": 1,
    "size": 1
  }
}

3. Execute

• Click "Try it out"

• Paste the JSON above

• Click "Execute"

4. Review Response

{
  "data": [
  {
            "id": "1_0_0xd215425f5a1c917973e7c34799942becabce66eed65310353e48d5342356e7f7",
            "chainId": 1,
            "marketType": 0,
            "marketId": "0xd215425f5a1c917973e7c34799942becabce66eed65310353e48d5342356e7f7",
            "name": "Supply sUSDe into ZAI",
            "description": "Market will return ZAI to the user upon withdrawal.",
            "category": "default",
            "owner": null,
            "underlyingVaultAddress": null,
            "lockupTime": "2592000",
            "frontendFee": "5000000000000000",
            "rewardStyle": 2,
            "tvlUsd": 0,
            "fillableUsd": 1177.209715532045,
            "capacityRatio": 1,
            "incentivesUsd": 1.1713529507781544,
            "yieldRate": 0.012106135986733001,
            "fixedYieldRate": 0.012106135986733001,
            "variableYieldRate": 0,
            "realYieldRate": 0,
            "tokenYieldRate": 0.012106135986733001,
            ...,          
            "isActive": true,
            "blockNumber": "21408360",
            "blockTimestamp": "1734271019",
            "transactionHash": "0xb35c4e9f6992b0f114bbb6e1aba45e513d2dfe66cea21b7ce01860077c3b5518",
            "logIndex": "46",
            "lastUpdated": "2025-06-20 18:19:01",
            "searchIndex": "0xd215425f5a1c917973e7c34799942becabce66eed65310353e48d5342356e7f7 supply susde into zai market will return zai to the user upon withdrawal. 0xb35c4e9f6992b0f114bbb6e1aba45e513d2dfe66cea21b7ce01860077c3b5518 susde ethena staked usde"
        }
  ],
  "page": {
    "index": 1,
    "size": 10,
    "total": 5
  },
  "count": 50
}

Common Use Cases

1. Fetch Market Positions

POST /api/v1/position/recipe
{
  "filters": [
    {
      "id": "rawMarketRefId",
      "value": "1_0_0x83c459782b2ff36629401b1a592354fc085f29ae00cf97b803f73cac464d389b"
    }
  ],
  "page": {
    "index": 1,
    "size": 500
  }
}

2. Get User's Total Assets

POST /api/v1/position/global/0x77777cc68b333a2256b436d675e8d257699aa667
{
  "page": {
    "index": 1,
    "size": 100
  }
}

3. Explore Markets by Criteria

POST /api/v1/market/explore
{
  "filters": [
    {
      "id": "chainId",
      "value": 1
    },
    {
      "id": "tvlUsd",
      "value": 1000000,
      "condition": "gte"
    }
  ],
  "sorting": [
    {
      "id": "tvlUsd",
      "desc": true
    }
  ],
  "page": {
    "index": 1,
    "size": 20
  }
}

Pagination

Most endpoints support pagination with these parameters:

Request

{
  "page": {
    "index": 1,    // Page number (1-based)
    "size": 500    // Items per page (max 500)
  }
}

Response

{
  "page": {
    "index": 1,    // Current page
    "size": 500,   // Items per page
    "total": 3     // Total pages
  },
  "count": 1500    // Total items
}

Filtering & Sorting

Filters

{
  "filters": [
    {
      "id": "chainId",           // Field to filter
      "value": 1,                // Filter value
      "condition": "eq"          // Condition (eq, gt, gte, lt, lte, in, etc.)
    }
  ]
}

Sorting

{
  "sorting": [
    {
      "id": "tvlUsd",           // Field to sort by
      "desc": true              // Descending order
    }
  ]
}

Next Steps

1. Explore the API: Try different endpoints in the interactive docs

2. Get an API key: Contact https://t.me/royco_support_bot to start the process of getting a key

3. Build Your App: Start integrating the API into your application

---

Ready to start building? Head over to the API documentation and try your first request!