{
  "openapi": "3.1.0",
  "info": {
    "title": "XLMarket API",
    "version": "1.0.0",
    "description": "Token launchpad on the Stellar network. Build unsigned transactions, sign them locally, submit. The platform never custodies your key. Read endpoints are public; launching and trading are in private beta. See /llms.txt."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/api/config": {
      "get": {
        "summary": "Platform config (network, fees, contract ids)",
        "responses": {
          "200": {
            "description": "Config object"
          }
        }
      }
    },
    "/api/tokens": {
      "get": {
        "summary": "List tokens with live metrics",
        "parameters": [
          {
            "name": "scope",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "interstellar",
                "all"
              ]
            },
            "description": "interstellar (our launches) or all (incl. existing XLM assets)"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of tokens with metrics"
          }
        }
      }
    },
    "/api/tokens/{id}": {
      "get": {
        "summary": "One token + metrics (id may be a launch id or ext-CODE-ISSUER)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Token with metrics"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/tokens/{id}/verify": {
      "get": {
        "summary": "Live on-chain legitimacy checks for a token",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result"
          }
        }
      }
    },
    "/api/tokens/{id}/candles": {
      "get": {
        "summary": "OHLC candles",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "interval",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                60,
                300,
                900,
                3600,
                86400
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ candles: [...] }"
          }
        }
      }
    },
    "/api/external/search": {
      "get": {
        "summary": "Find any existing Stellar asset by code/issuer/domain",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{ tokens: [...] }"
          }
        }
      }
    },
    "/api/portfolio": {
      "get": {
        "summary": "Holdings for an account",
        "parameters": [
          {
            "name": "account",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^G[A-Z2-7]{55}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Portfolio"
          },
          "400": {
            "description": "Invalid account"
          }
        }
      }
    },
    "/api/trade/build": {
      "post": {
        "summary": "Build an unsigned buy/sell transaction (1% fee included; an optional referrer is paid 20% of that fee)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "tokenId",
                  "side",
                  "amount",
                  "traderAccount"
                ],
                "properties": {
                  "tokenId": {
                    "type": "string"
                  },
                  "side": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "sell"
                    ]
                  },
                  "amount": {
                    "type": "number",
                    "description": "buy: XLM to spend; sell: tokens to sell"
                  },
                  "slippageBps": {
                    "type": "integer",
                    "default": 100
                  },
                  "traderAccount": {
                    "type": "string",
                    "pattern": "^G[A-Z2-7]{55}$"
                  },
                  "referrer": {
                    "type": "string",
                    "pattern": "^G[A-Z2-7]{55}$",
                    "description": "Optional. The address that referred this trader. It receives 20% of the platform fee as a second payment inside the same transaction. Must be an existing account and not the trader."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ xdr, estimatedOut, minReceived, feeXlm, priceImpactPct }"
          }
        }
      }
    },
    "/api/submit": {
      "post": {
        "summary": "Submit a signed transaction XDR to the network",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "xdr"
                ],
                "properties": {
                  "xdr": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ hash, successful }"
          }
        }
      }
    },
    "/api/launch/prepare": {
      "post": {
        "summary": "Step 1 of a standard launch: get the pre-step unsigned tx",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "ticker",
                  "totalSupply",
                  "devAllocationPct",
                  "initialLiquidityXlm",
                  "creatorAccount"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "ticker": {
                    "type": "string"
                  },
                  "totalSupply": {
                    "type": "number"
                  },
                  "devAllocationPct": {
                    "type": "number"
                  },
                  "initialLiquidityXlm": {
                    "type": "number"
                  },
                  "antiSniper": {
                    "type": "boolean"
                  },
                  "imageUrl": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string"
                  },
                  "twitter": {
                    "type": "string"
                  },
                  "telegram": {
                    "type": "string"
                  },
                  "creatorAccount": {
                    "type": "string",
                    "pattern": "^G[A-Z2-7]{55}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ jobId, issuer, xdr, requiredXlm }"
          }
        }
      }
    },
    "/api/launch/finalize": {
      "post": {
        "summary": "Step 2: finalize a launch after the pre-step tx is submitted",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jobId",
                  "txHash"
                ],
                "properties": {
                  "jobId": {
                    "type": "string"
                  },
                  "txHash": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Live token record"
          }
        }
      }
    },
    "/api/tokens/{id}/trades": {
      "get": {
        "summary": "Recent trades for a token",
        "description": "Launches here read their own AMM pool; existing Stellar assets read the whole DEX by asset pair. `stale: true` means the upstream fetch failed, which is different from having no trades.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Token id, or `ext-CODE-ISSUER` for an existing Stellar asset."
          }
        ],
        "responses": {
          "200": {
            "description": "Recent trades, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "trades": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "time": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "side": {
                            "type": "string",
                            "enum": [
                              "buy",
                              "sell"
                            ]
                          },
                          "xlmAmount": {
                            "type": "number"
                          },
                          "tokenAmount": {
                            "type": "number"
                          },
                          "price": {
                            "type": "number"
                          },
                          "trader": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "stale": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown token."
          }
        }
      }
    }
  }
}