Querying Retroshades

For each retroshade struct defined in the contract, a table on the database will be created that can be queried using POST /retroshade/query:

curl -X POST https://mainnet.mercurydata.app/rest/retroshade/query \
-H "Authorization: Bearer <yourjwt>" \
-H 'Content-Type: application/json' \
-d '{
  "query": "SELECT * FROM retroshade.program_1_liquidity_event LIMIT 50"
}'

Table naming

Tables are named retroshade.program_{id}_{target} where:

• id is the integer ID assigned to your program at deploy time (returned by POST /retroshade/deploy and visible in GET /retroshade/list)

• target is the snake_case version of the struct name used in your retroshade emit (e.g. LiquidityEvent becomes liquidity_event)

To discover the exact table names for your programs, use GET /retroshade/tables:

curl https://mainnet.mercurydata.app/rest/retroshade/tables \
-H "Authorization: Bearer <yourjwt>"

Response:

[
  {
    "table_name": "program_1_liquidity_event",
    "project_name_plain": "my-retroshade-program"
  }
]

Mercury-injected columns

Every retroshade table has three columns added automatically by Mercury. Do not define these in your struct:

Column	Type	Description
contract_id	TEXT	Soroban contract that triggered the emit
transaction	TEXT	Transaction hash
_mercury_event_id	TEXT UNIQUE	Mercury dedup key -- do not use as a semantic identifier

List Retroshades Subscriptions

Returns all retroshade programs deployed by the authenticated user.

Endpoint: GET /retroshade/list

curl https://mainnet.mercurydata.app/rest/retroshade/list \
-H "Authorization: Bearer <yourjwt>"

Response:

[
  {
    "id": 1,
    "project_name": "my-retroshade-program",
    "contracts": [
      "CDVNV4..."
    ],
    "running": true
  }
]