Muon API Queries

Introduction

The Muon API is designed to provide signed data for SYMM 3rd Party frontends, a platform that enables users to trade assets and perpetual contracts (perps) without the need for Know Your Customer (KYC) procedures. By utilizing their Ethereum wallet, users can participate in trading activities on Cloverfield.

Muon acts as an intermediary service, facilitating the generation and signing of data that is required for trading. This documentation will provide an overview of the app codebase, explaining its key components and functionalities.

Overview of the Muon API

The Muon API is designed to provide various data related to parties, unrealized profit and loss (uPnl) and price data. It offers separate uPnl calculations for individual parties, namely "partyA" and "partyB," as well as combined uPnl calculations for both parties together. Additionally, the API allows fetching the prices of given quotes. The following sections provide technical documentation of each method.

API Query Endpoints

The Muon app can be queried using these URLs, if one is unresponsive please try another.

• https://muon-oracle1.rasa.capital/v1/

• https://muon-oracle2.rasa.capital/v1/

• https://muon-oracle3.rasa.capital/v1/

• https://muon-oracle4.rasa.capital/v1/

• https://polygon-testnet-oracle.rasa.capital/v1/: Polygon

uPnl_A

The uPnl_A method in the Muon app is designed to verify and validate the unrealized profit and loss (uPnl) for partyA based on a set tolerance level.

Input Parameters

• partyA: The address of partyA.

• chainId: The chain identifier.

• symmio: Address of the Symmio diamond.

Returned Data Structure

• symmio: Address of the Symmio diamond.

• partyA: The address of partyA.

• nonce: Unique nonce for the transaction to prevent replay attacks.

• uPnl: The verified uPnl value for partyA as obtained from the request data.

• timestamp: The blockchain timestamp at which the request data was generated.

• chainId: The chain identifier.

Example API Query

https://muon-oracle4.rasa.capital/v1/?app=symmio&method=uPnl_A&params[partyA]=$address&params[chainId]=$chainId&params[symmio]=$symmio

Example Response

{
    "success": true,
    "result": {
        "reqId": "",
        "app": "symmio",
        "appId": "",
        "method": "uPnl_A",
        "data": {
            "params": {
                "partyA": "",
                "chainId": "",
                "symmio": "",
                "latestBlockNumber": ""
            },
            "timestamp": ,
            "uid": "",
            "result": {
                "chainId": "",
                "partyA": "",
                "symmio": "",
                "liquidationId": "",
                "latestBlockNumber": "",
                "uPnl": "",
                "loss": "",
                "notionalValueSum": "",
                "nonce": "",
                "quoteIds": [],
                "symbolIds": [],
                "symbolIdsPrices": [],
                "prices": [],
                "pricesMap": {
                }
            }
        }
    }

partyA_overview

The partyA_overview method in the Muon API provides a comprehensive overview of partyA's trading status, including the unrealized profit and loss (uPnl), loss, notional value sum, and other relevant financial data. This method ensures detailed insight into partyA's trading performance and current market position.

Input Parameters

• partyA: The address of partyA.

• chainId: The chain identifier.

• symmio: Address of the Symmio diamond.

Returned Data Structure

• symmio: Address of the Symmio diamond.

• partyA: The address of partyA.

• nonce: Unique nonce for the transaction to prevent replay attacks.

• uPnl: The verified uPnl value for partyA as obtained from the request data.

• timestamp: The blockchain timestamp at which the request data was generated.

Example API Query

https://muon-oracle4.rasa.capital/v1/?app=symmio&method=partyA_overview&params[partyA]=$address&params[chainId]=$chainId&params[symmio]=$symmio

Example Response

{
    "success": true,
    "result": {
        "reqId": "",
        "app": "symmio",
        "appId": "",
        "method": "partyA_overview",
        "data": {
            "params": {
                "partyA": "",
                "chainId": "",
                "symmio": "",
                "latestBlockNumber": ""
            },
            "timestamp": int,
            "uid": "",
            "result": {
                "chainId": "",
                "partyA": "",
                "symmio": "",
                "liquidationId": "",
                "latestBlockNumber": "",
                "uPnl": "",
                "loss": "",
                "notionalValueSum": "",
                "nonce": "",
                "quoteIds": [],
                "symbolIds": [],
                "symbolIdsPrices": [],
                "prices": [],
                "pricesMap": {
                }
                "signParams": []
            }
        }
    }
}

uPnl_A_withSymbolPrice

The uPnl_A_withSymbolPrice method in the Muon API calculates the unrealized profit and loss (uPnl) for partyA and fetches the current price of a specified symbol.

Input Parameters

• partyA: The address of partyA.

• chainId: The chain identifier.

• symbolId: The identifier of the trading symbol.

• symmio: Address of the Symmio diamond.

Returned Data Structure

• chainId: The chain identifier.

• partyA: The address of partyA.

• symbolId: The identifier of the trading symbol.

• price: The current price of the specified symbol.

• symmio: Address of the Symmio diamond.

• Additional data included as the result.

Example API Query

https://muon-oracle4.rasa.capital/v1/?app=symmio&method=uPnl_A_withSymbolPrice&params[partyA]=$address&params[chainId]=$chainId&params[symbolId]=$symbolId&params[symmio]=$symmio

Example Response:

{
    "success": true,
    "result": {
        "reqId": "",
        "app": "",
        "appId": "",
        "method": "",
        "data": {
            "params": {
                "partyA": "",
                "chainId": "",
                "symbolId": "",
                "symmio": "",
                "latestBlockNumber": ""
            },
            "timestamp": int,
            "uid": "",
            "result": {
                "chainId": "",
                "partyA": "",
                "symbolId": "",
                "price": "",
                "symmio": "",
                "latestBlockNumber": "",
                "uPnl": "",
                "loss": "",
                "notionalValueSum": "",
                "nonce": "",
                "quoteIds": [],
                "symbolIds": [],
                "symbolIdsPrices": [],
                "prices": [],
                "pricesMap": {}
                "maxLeverages": {}
"signParams": []

uPnl_B

The uPnl_B method within the Muon API calculates the unrealized profit and loss (uPnl) specifically for partyB in relation to partyA.

Input Parameters

• partyB: The address of partyB.

• partyA: The address of partyA.

• chainId: The chain identifier.

• symmio: Address of the Symmio diamond.

• latestBlockNumber: The latest block number to fetch data for.

Returned Data Structure

• chainId: The chain identifier.

• partyB: The address of partyB.

• partyA: The address of partyA.

• symmio: Address of the Symmio diamond.

• latestBlockNumber: The latest block number at the time of the query.

• Additional data included as the result.

Example API Query

https://muon-oracle4.rasa.capital/v1/?app=symmio&method=uPnl_B&params[partyB]=$partyB_address&params[partyA]=$partyA_address&params[chainId]=$chainId&params[symmio]=$symmio

Example Response:

{
    "success": true,
    "result": {
        "reqId": "",
        "app": "symmio",
        "appId": "",
        "method": "uPnl_B",
        "data": {
            "params": {
                "partyB": "",
                "partyA": "",
                "chainId": "",
                "symmio": "",
                "latestBlockNumber": ""
            },
            "timestamp": int,
            "uid": "",
            "result": {
                "chainId": "",
                "partyB": "",
                "partyA": "",
                "symmio": "",
                "latestBlockNumber": "",
                "uPnl": "",
                "notionalValueSum": "",
                "nonce": "",
                "quoteIds": []
            },
        }
    }
}

uPnl

The uPnl method within the Muon API calculates the combined unrealized profit and loss (uPnl) for both partyB and partyA. This method provides a comprehensive view of the financial performance and interactions between the two parties.

Input Parameters

• partyB: The address of partyB.

• partyA: The address of partyA.

• chainId: The chain identifier.

• symmio: Address of the Symmio diamond.

Returned Data Structure

• chainId: The chain identifier.

• partyB: The address of partyB.

• partyA: The address of partyA.

• symmio: Address of the Symmio diamond.

• latestBlockNumber: The latest block number at the time of the query.

• Additional data included as the result.

Example API Query

https://muon-oracle4.rasa.capital/v1/?app=symmio&method=uPnl&params[partyB]=$partyB_address&params[partyA]=$partyA_address&params[chainId]=$chainId&params[symmio]=$symmio

Example Response:

{
    "success": true,
    "result": {
        "reqId": "",
        "app": "",
        "appId": "",
        "method": "uPnl",
        "data": {
            "params": {
                "partyB": "",
                "partyA": "",
                "chainId": "",
                "symmio": "",
                "latestBlockNumber": ""
            },
            "timestamp": int,
            "uid": "",
            "result": {
                "chainId": "",
                "partyB": "",
                "partyA": "",
                "symmio": "",
                "latestBlockNumber": "",
                "uPnlB": "",
                "uPnlA": "",
                "notionalValueSumB": "",
                "notionalValueSumA": "",
                "nonceB": "",
                "nonceA": "",
                "pricesMap": {}
                "signParams": [

                }
            }
        }
    }
}

uPnlWithSymbolPrice

The uPnlWithSymbolPrice method within the Muon API calculates the combined unrealized profit and loss (uPnl) for both partyB and partyA and fetches the current price of a specified symbol. This method provides comprehensive financial performance metrics for both parties and the latest symbol price.

Input Parameters

• partyB: The address of partyB.

• partyA: The address of partyA.

• chainId: The chain identifier.

• symbolId: The identifier of the trading symbol.

• symmio: Address of the Symmio diamond.

Returned Data Structure

• chainId: The chain identifier.

• partyB: The address of partyB.

• partyA: The address of partyA.

• symbolId: The identifier of the trading symbol.

• price: The current price of the specified symbol.

• symmio: Address of the Symmio diamond.

• latestBlockNumber: The latest block number at the time of the query.

• Additional data included as the result.

Example API Query

https://muon-oracle4.rasa.capital/v1/?app=symmio&method=uPnlWithSymbolPrice&params[partyB]=$partyB_address&params[partyA]=$partyA_address&params[chainId]=$chainId&params[symbolId]=$symbolId&params[symmio]=$symmio&params[latestBlockNumber]=$latestBlockNumber

Example Response

{
    "success": true,
    "result": {
        "reqId": "",
        "app": "symmio",
        "appId": "",
        "method": "uPnlWithSymbolPrice",
        "data": {
            "params": {
                "partyB": "",
                "partyA": "",
                "chainId": "",
                "symbolId": "",
                "symmio": "",
                "latestBlockNumber": ""
            },
            "timestamp": int,
            "uid": "",
            "result": {
                "chainId": "",
                "partyB": "",
                "partyA": "",
                "symbolId": "",
                "price": "",
                "symmio": "",
                "latestBlockNumber": "",
                "uPnlB": "",
                "uPnlA": "",
                "notionalValueSumB": "",
                "notionalValueSumA": "",
                "nonceB": "",
                "nonceA": "",
                "pricesMap": {},
                "maxLeverages": {},
                "markPrices": {
                    "binance": {}
                },
                "pricesB": [],
                "pricesA": [],
                "quoteIdsB": [],
                "quoteIdsA": []
                }
            }
        }

price

The price method within the Muon API fetches the current prices of specified quotes. This method provides up-to-date pricing information for a list of trading symbols.

Input Parameters

• quoteIds: A JSON-formatted list of quote identifiers.

• chainId: The chain identifier.

• symmio: Address of the Symmio diamond.

Returned Data Structure

• chainId: The chain identifier.

• quoteIds: The list of quote identifiers.

• symmio: Address of the Symmio diamond.

• latestBlockNumber: The latest block number at the time of the query.

• Additional price data as included in the result from fetchPrices.

Example API Query

https://muon-oracle4.rasa.capital/v1/?app=symmio&method=price&params[quoteIds]=$quoteIds&params[chainId]=$chainId&params[symmio]=$symmio

Example Response:

{
    "success": true,
    "result": {
        "reqId": "",
        "app": "symmio",
        "appId": "",
        "method": "price",
        "data": {
            "params": {
                "quoteIds": "[\"1000\",\"1001\",\"1002\"]",
                "chainId": "",
                "symmio": "",
                "latestBlockNumber": ""
            },
            "timestamp": int,
            "uid": "",
            "result": {
                "chainId": "",
                "quoteIds": [
                    "",
                    "",
                    ""
                ],
                "symmio": "",
                "latestBlockNumber": "",
                "symbols": [
                    "",
                    "",
                    ""
                ],
                "prices": [
                    "",
                    "",
                    ""
                ],
                "pricesMap": {
                }
            }
        }
    }
}

settle_upnl

The settle_upnl method is used to verify settlement calculations for one or more open positions (represented by quoteIds) for a given party. It finalizes the unrealized profit and loss (uPnl) for these positions and returns the settlement data, including the updated uPnl values, notional sums, and nonces required for verification and on-chain settlement. You can read more about settleUpnl() here.

Input Parameters

• partyA: The address of partyA for whom the settlement calculation is performed.

• chainId: The chain identifier.

• symmio: Address of the Symmio diamond.

• quoteIds: A JSON-formatted list of quote identifiers to be settled (e.g., "[18068]").

Note: latestBlockNumber is not explicitly required in the example. The Muon backend will fetch the appropriate block data internally.

---

Returned Data Structure

• chainId: The chain identifier.

• partyA: The address of partyA.

• symmio: Address of the Symmio diamond.

• latestBlockNumber: The latest block number at the time of the query.

• quoteSettlementData: An array containing settlement information for each quoteId.

  • Each item includes:

    • quoteId

    • currentPrice

    • partyBUpnlIndex

• uPnlA: The finalized unrealized profit/loss for partyA across all settled quotes.

• upnlPartyBs: An array of the finalized unrealized PnL values for each corresponding counterparty.

• notionalValueSumA: The total notional value of all positions held by partyA.

• notionalValueSumBs: An array of the total notional values for each corresponding partyB.

• nonceA: The updated nonce for partyA after settlement.

• noncePartyBs: An array of updated nonces for each corresponding partyB.

• signParams: An array containing the parameters used to sign and verify the settlement on-chain.

---

Example API Query

https://muon-oracle4.rasa.capital/v1/?app=symmio&method=settle_upnl&params[partyA]=0x33D689034225A67454980c9D91E35C03a4765B30&params[chainId]=42161&params[symmio]=0x8F06459f184553e5d04F07F868720BDaCAB39395&params[quoteIds]=[18068]

---

Example Response

{
    "success": true,
    "result": {
        "reqId": "",
        "app": "symmio",
        "appId": "",
        "method": "settle_upnl",
        "data": {
            "params": {
                "partyA": "",
                "chainId": "42161",
                "symmio": "",
                "quoteIds": ""
            },
            "timestamp": 1736965079,
            "uid": "",
            "result": {
                "chainId": "",
                "partyA": "",
                "symmio": "",
                "latestBlockNumber": "",
                "quoteSettlementData": [
                    [
                        "18068",
                        "2910661810000000000",
                        0
                    ]
                ],
                "uPnlA": "",
                "upnlPartyBs": [
                    ""
                ],
                "notionalValueSumA": "",
                "notionalValueSumBs": [
                    ""
                ],
                "nonceA": "11",
                "noncePartyBs": [
                    "11"
                ]
            },
            "signParams": [
                {
                    "name": "appId",
                    "type": "uint256",
                    "value": ""
                },
                {
                    "name": "reqId",
                    "type": "bytes",
                    "value": ""
                },
                {
                    "type": "address",
                    "value": ""
                },
                {
                    "type": "string",
                    "value": "verifySettlement"
                },
                {
                    "type": "uint256[]",
                    "value": [
                        "11"
                    ]
                },
                {
                    "type": "uint256",
                    "value": ""
                },
                {
                    "type": "bytes",
                    "value": ""
                },
                {
                    "type": "int256[]",
                    "value": [
                        "-"
                    ]
                },
                {
                    "type": "int256",
                    "value": ""
                },
                {
                    "type": "uint256",
                    "value": 
                },
                {
                    "type": "uint256",
                    "value": ""
                }
            ],
            "resultHash": "",
            "init": {
                "nonceAddress": ""
            }
        },
        "signatures": [
            {
                "owner": "",
                "ownerPubKey": {
                    "x": "",
                    "yParity": "0"
                },
                "signature": ""
            }
        ],
        "gwAddress": "",
        "shieldAddress": "",
        "shieldSignature": "",
        "nodeSignature": "",
        "confirmed": true
    }
}