# Getting started with the Royco API #### 1. Get Your API Key * **For Production**: Contact the Royco team on telegram at 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) * **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) * **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 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! --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.royco.org/royco-api/getting-started-with-the-royco-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.