GhostSwap

List all coins GhostSwap supports for swapping (1,600+ assets). Use lite=true for just an array of tickers (e.g. ["btc","eth","ltc"]).

{
  "type": "object",
  "properties": {
    "lite": {
      "description": "Return just tickers (default false — full metadata).",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get the min and max swap amount for a single (from, to) pair. Returns separate min/max for float-rate and fixed-rate modes.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "Source currency ticker, lowercase (e.g. \"btc\")."
    },
    "to": {
      "type": "string",
      "description": "Destination currency ticker, lowercase (e.g. \"eth\")."
    }
  },
  "required": [
    "from",
    "to"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check whether a wallet address is valid for a given currency. Returns {valid:true} or {valid:false,message}. Permissive pre-check — create_swap runs a stricter validator.

{
  "type": "object",
  "properties": {
    "currency": {
      "type": "string",
      "description": "Ticker, lowercase."
    },
    "address": {
      "type": "string",
      "description": "The wallet address to validate."
    }
  },
  "required": [
    "currency",
    "address"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get a live swap quote — rate, amountUserReceives, network fee, min/max. Always display amountUserReceives (not amountTo). mode="fixed" locks the rate and returns a short-lived rateId.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "Source currency ticker."
    },
    "to": {
      "type": "string",
      "description": "Destination currency ticker."
    },
    "amountFrom": {
      "type": "string",
      "description": "Decimal amount as a STRING (e.g. \"0.01\"). Strings preserve precision."
    },
    "mode": {
      "description": "Float (default) settles at market; fixed locks via rateId.",
      "type": "string",
      "enum": [
        "float",
        "fixed"
      ]
    }
  },
  "required": [
    "from",
    "to",
    "amountFrom"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Create a new swap. Returns payinAddress where the end-user must send funds. REQUIRES refundAddress (the user's own wallet on the FROM chain). IDEMPOTENT — pass a stable idempotencyKey (UUID v4) per logical "Confirm" and reuse it on retries; never create the same swap twice. If a result has stop:true, relay its neutral userMessage and STOP — never tell the user an address is flagged/screened, never name an address, never suggest "try a different address", never retry.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "amountFrom": {
      "type": "string",
      "description": "Decimal as STRING."
    },
    "address": {
      "type": "string",
      "description": "Where the user receives the \"to\" currency."
    },
    "refundAddress": {
      "type": "string",
      "description": "REQUIRED — the user's OWN wallet on the FROM chain (the wallet they're sending from); refunds return here if the swap can't complete."
    },
    "mode": {
      "type": "string",
      "enum": [
        "float",
        "fixed"
      ]
    },
    "rateId": {
      "description": "Required when mode=fixed; from get_quote.",
      "type": "string"
    },
    "idempotencyKey": {
      "description": "UUID v4 — one per logical Confirm, reused on retries. Auto-generated if omitted.",
      "type": "string"
    }
  },
  "required": [
    "from",
    "to",
    "amountFrom",
    "address",
    "refundAddress"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Get the current status of a swap by id. Poll every 10–30s after create_swap until terminal: finished | failed | refunded | overdue | expired. `hold` = AML/KYC review (slow polling; direct end-user to [email protected]).

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The swap id from create_swap."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}