# 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](https://api.royco.org/api) 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`](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}`](https://api.royco.org/api#/Market/MarketController_getMarket)
* **Get all Markets**: `POST` [`/api/v1/market/explore`](https://api.royco.org/api#/Market/MarketController_getMarkets)

#### Positions

* **Recipe Positions**: `POST` [`/api/v1/position/recipe`](https://api.royco.org/api#/Position/PositionController_getRecipePositions)
* **Vault Positions**: `POST` [`/api/v1/position/vault`](https://api.royco.org/api#/Position/PositionController_getVaultPositions)&#x20;
* **Global Positions**: `POST` [`/api/v1/position/global/{accountAddress}`](https://api.royco.org/api#/Position/PositionController_getGlobalPositions)

#### Offers

* **Recipe Offers**: `POST` [`/api/v1/offer/recipe`](https://api.royco.org/api#/Offer/OfferController_getRecipeOffers)&#x20;
* **Vault Offers**: `POST` [`/api/v1/offer/vault`](https://api.royco.org/api#/Offer/OfferController_getVaultOffers)

### 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](https://api.royco.org/api#/Market/MarketController_getMarkets) in the API docs

#### 2. Add Filters

```json
{
  "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

```json
{
  "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

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

#### 2. Get User's Total Assets

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

#### 3. Explore Markets by Criteria

```json
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

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

#### Response

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

### Filtering & Sorting

#### Filters

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

#### Sorting

```json
{
  "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](https://api.royco.org/api) and try your first request!