MetaQuote

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/getchord-xyz/json-schema/getchord-xyz-meta-quote-schema.json",
  "title": "MetaQuote",
  "description": "The same shape whichever provider answered.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/getchord-xyz-openapi.json#/components/schemas/MetaQuote",
  "type": "object",
  "properties": {
    "chain": {
      "type": "integer",
      "description": "Chain id."
    },
    "tokenIn": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "EVM address, hex, case-insensitive."
    },
    "tokenOut": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "EVM address, hex, case-insensitive."
    },
    "amountIn": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "Amount in the token's smallest unit, as a decimal string. Never a float."
    },
    "taker": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "The wallet the transaction was built and simulated for; null on a price-only quote."
    },
    "slippageBps": {
      "type": "integer",
      "description": "The slippage `minAmountOut` reflects."
    },
    "provider": {
      "type": [
        "string",
        "null"
      ],
      "description": "Who answered: `chord` (Chord's own router), `kyberswap`, `monorail`, `lifi`, `relay`. `null` = no provider has a route."
    },
    "fallbackReason": {
      "type": [
        "string",
        "null"
      ],
      "description": "`null` when Chord answered. Otherwise why it did not: `no_route`, `insufficient_liquidity`, `engine_error`, `engine_timeout`, `engine_down`, `value_guard`, `taxed_token`, `route_stale`, `chain_not_live`, `build_failed`, `simulation_failed`."
    },
    "attempts": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/MetaAttempt"
      },
      "description": "Every provider asked, in order."
    },
    "amountOut": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "What the taker receives after every fee, smallest unit of `tokenOut`. (`/quote`'s `outputAmount` is before Chord's fee; this is after.)"
    },
    "minAmountOut": {
      "type": "string",
      "pattern": "^\\d+$",
      "description": "The minimum the transaction enforces, from the slippage you asked for."
    },
    "priceImpactPct": {
      "type": [
        "string",
        "null"
      ],
      "description": "Percent, when the provider states one."
    },
    "valueLossPct": {
      "type": [
        "number",
        "null"
      ],
      "description": "Output value against input value at Chord's own prices, percent (negative = worth more). `null` when Chord has no reliable price for a side: see `safety` and `warnings`."
    },
    "feeBps": {
      "type": "integer",
      "description": "Chord path: Chord's protocol fee on the output. Fallback: the integrator fee Chord added (0 today); the provider's own fees are already inside `amountOut`."
    },
    "feeRecipient": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "EVM address, hex, case-insensitive."
    },
    "route": {
      "type": "object",
      "properties": {
        "venues": {
          "type": "array",
          "items": {
            "type": "string",
            "description": ""
          },
          "description": "Venue names."
        }
      }
    },
    "tx": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "to": {
          "type": "string",
          "pattern": "^0x[a-fA-F0-9]{40}$",
          "description": "EVM address, hex, case-insensitive."
        },
        "data": {
          "type": "string",
          "description": "Calldata."
        },
        "value": {
          "type": "string",
          "pattern": "^\\d+$",
          "description": "Amount in the token's smallest unit, as a decimal string. Never a float."
        },
        "gas": {
          "type": [
            "string",
            "null"
          ],
          "description": "Gas limit to sign with."
        },
        "chainId": {
          "type": "integer",
          "description": ""
        }
      },
      "description": "The UNSIGNED transaction. `null` without `taker`. `to` is the Chord router when `provider` is `chord`, the provider's own router otherwise."
    },
    "approval": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "token": {
          "type": "string",
          "pattern": "^0x[a-fA-F0-9]{40}$",
          "description": "EVM address, hex, case-insensitive."
        },
        "spender": {
          "type": "string",
          "pattern": "^0x[a-fA-F0-9]{40}$",
          "description": "EVM address, hex, case-insensitive."
        },
        "amount": {
          "type": "string",
          "pattern": "^\\d+$",
          "description": "Amount in the token's smallest unit, as a decimal string. Never a float."
        },
        "resetFirst": {
          "type": "boolean",
          "description": "Present only for a token that reverts `approve(x > 0)` while its allowance is non-zero (USDT on Ethereum). `true` = the taker has a left-over allowance: send `approve(spender, 0)` first, then this approval."
        }
      },
      "description": "The approval to send first. `null` for a native input or when the taker's allowance already covers the amount."
    },
    "simulation": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "ok": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "`true` = ran and delivered at least `minAmountOut`; `null` = no verdict (only ever returned on the Chord path)."
        },
        "amountOut": {
          "type": "string",
          "pattern": "^\\d+$",
          "description": "Amount in the token's smallest unit, as a decimal string. Never a float."
        },
        "gasUsed": {
          "type": "integer",
          "description": ""
        },
        "revert": {
          "type": "string",
          "description": ""
        },
        "reason": {
          "type": "string",
          "description": ""
        }
      },
      "description": "The transaction run as the taker (with the input supplied when the taker does not hold it), measuring the taker's own balance change. `null` without `taker`."
    },
    "safety": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "source": {
          "type": "string",
          "description": "`goplus`"
        },
        "token": {
          "type": "string",
          "pattern": "^0x[a-fA-F0-9]{40}$",
          "description": "EVM address, hex, case-insensitive."
        },
        "worstFlag": {
          "type": "string",
          "description": "`none`, `low`, `medium`, `high`."
        },
        "honeypot": {
          "type": [
            "boolean",
            "null"
          ],
          "description": ""
        },
        "buyTaxPct": {
          "type": [
            "number",
            "null"
          ],
          "description": ""
        },
        "sellTaxPct": {
          "type": [
            "number",
            "null"
          ],
          "description": ""
        },
        "risks": {
          "type": "array",
          "items": {
            "type": "string",
            "description": ""
          }
        }
      },
      "description": "A security scan of the unknown token, present when the value check could not run on a fallback answer."
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string",
        "description": ""
      },
      "description": "`INSUFFICIENT_BALANCE`, `UNPRICED`, `OUTPUT_WRAPPED`, `NO_ROUTE`, and on a price-only fallback `PRICE_CHECKED` (built and simulated for a placeholder wallet) or `UNVERIFIED_PRICE` (built, not simulatable) — each followed by a sentence."
    },
    "quoteId": {
      "type": "string",
      "description": "Pass to `POST /meta/swap` within 2 minutes."
    },
    "expiresAt": {
      "type": "integer",
      "description": "Unix time, seconds, UTC."
    }
  },
  "$defs": {
    "MetaAttempt": {
      "type": "object",
      "properties": {
        "provider": {
          "type": "string",
          "description": "`chord`, `kyberswap`, `monorail`, `lifi` or `relay`."
        },
        "status": {
          "type": "string",
          "description": "`ok`, or why this provider did not produce the answer: `no_route`, `timeout`, `http_error`, `rate_limited`, `invalid_response`, `not_allowlisted`, `calldata_mismatch`, `min_out_too_low`, `value_gap`, `unsafe_token`, `simulation_failed`, `unverified`, `breaker_open`, `skipped`; for Chord also `engine_error`, `engine_timeout`, `engine_down`, `route_refused`, `build_failed`, `chain_not_live`."
        },
        "ms": {
          "type": "integer",
          "description": "Time spent on this provider."
        },
        "error": {
          "type": [
            "string",
            "null"
          ],
          "description": "Short reason from a fixed vocabulary, never provider text."
        }
      },
      "description": "One provider that was asked, in order."
    }
  }
}