API reference

Built from the OpenAPI 3.1.0 document of the Qiguard API, version 1.0.0. Download it as openapi.yaml or openapi.json.

Base URL https://api.qiguard.com. Keyed endpoints need the headers qg-api-key and qg-version: v1; keyless endpoints need no header. Every response carries the header qg-zid and the body field zid.

Endpoints

GET /swap/allowance-holder/price

Indicative price for an allowance-holder swap.

• Key: API key (qg-api-key) and qg-version: v1
• Endpoint id: swap.price (the name used in the dashboard usage tables)
• Operation id: swap_allowanceholderGetPrice

Parameters of GET /swap/allowance-holder/price

Responses of GET /swap/allowance-holder/price

curl -s "https://api.qiguard.com/swap/allowance-holder/price?chainId=8453&sellToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&buyToken=0x4200000000000000000000000000000000000006&sellAmount=25000000" \
  -H "qg-api-key: $QG_API_KEY" -H "qg-version: v1"

GET /swap/allowance-holder/quote

Firm quote with the transaction to send.

Same parameters as the price endpoint; taker is required. transaction.data calls marketSwap, marketSwapNativeToToken or marketSwapTokenToNative on the settlement contract, followed by the 18-byte Qiguard tag (qiguard.tag). Approve issues.allowance.spender for the exact sellAmount, wait for the approval receipt, then quote again: transaction expires at expiresAt.

• Key: API key (qg-api-key) and qg-version: v1
• Endpoint id: swap.quote (the name used in the dashboard usage tables)
• Operation id: swap_allowanceholderGetQuote

Parameters of GET /swap/allowance-holder/quote

Responses of GET /swap/allowance-holder/quote

curl -s "https://api.qiguard.com/swap/allowance-holder/quote?chainId=8453&sellToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&buyToken=0x4200000000000000000000000000000000000006&sellAmount=25000000&taker=0x1111111111111111111111111111111111111111" \
  -H "qg-api-key: $QG_API_KEY" -H "qg-version: v1"

The example taker 0x1111111111111111111111111111111111111111 is a placeholder: replace it with your wallet address.

GET /gasless/price

Indicative price for a gasless swap.

ERC-20 to ERC-20 only (the wrapped native token is allowed, the native coin is not). On a chain listed by /gasless/chains with enabled: false the price is still returned, with the warning gasless_not_enabled. With a taker whose balance is below sellAmount, the price is still returned and issues.balance shows the shortfall; only /gasless/quote answers 400 INSUFFICIENT_BALANCE.

• Key: API key (qg-api-key) and qg-version: v1
• Endpoint id: gasless.price (the name used in the dashboard usage tables)
• Operation id: gasless_getPrice

Parameters of GET /gasless/price

Responses of GET /gasless/price

curl -s "https://api.qiguard.com/gasless/price?chainId=8453&sellToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&buyToken=0x4200000000000000000000000000000000000006&sellAmount=25000000" \
  -H "qg-api-key: $QG_API_KEY" -H "qg-version: v1"

GET /gasless/quote

Gasless quote with the Permit2 witness message to sign.

taker is required. Sign trade.eip712 with eth_signTypedData_v4 and send it to POST /gasless/submit. approval is always null in v1: a taker without a Permit2 allowance must first send one normal approve(Permit2, amount) transaction and pay its gas (issues.allowance shows it). A taker balance below sellAmount gives 400 INSUFFICIENT_BALANCE. Before signing, check that domain.verifyingContract is Permit2, message.spender is the settlement contract of the chain and witness.recipient is the taker (the SDK's assertGaslessTrade does this).

• Key: API key (qg-api-key) and qg-version: v1
• Endpoint id: gasless.quote (the name used in the dashboard usage tables)
• Operation id: gasless_getQuote

Parameters of GET /gasless/quote

Responses of GET /gasless/quote

curl -s "https://api.qiguard.com/gasless/quote?chainId=8453&sellToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&buyToken=0x4200000000000000000000000000000000000006&sellAmount=25000000&taker=0x1111111111111111111111111111111111111111" \
  -H "qg-api-key: $QG_API_KEY" -H "qg-version: v1"

The example taker 0x1111111111111111111111111111111111111111 is a placeholder: replace it with your wallet address.

POST /gasless/submit

Submit a signed gasless trade.

Idempotent by tradeHash (the EIP-712 digest): the same trade from the same app returns 200 with the same body; from another app it returns 400 TRADE_ALREADY_SUBMITTED. An optional Idempotency-Key header is also honoured for 24 hours. Until gasless is enabled on the chain (relayer funded and switched on), this endpoint returns 503 GASLESS_NOT_ENABLED with data.reason = "gasless_not_enabled". A 503 RELAYER_UNAVAILABLE with data.reason relayer_timeout or relayer_unreachable carries data.tradeHash: the trade may still have been accepted, so read GET /gasless/status/{tradeHash} (404 means it was not) before quoting and signing again; sending the same body again returns the earlier answer.

• Key: API key (qg-api-key) and qg-version: v1
• Endpoint id: gasless.submit (the name used in the dashboard usage tables)
• Operation id: gasless_submit

Parameters of POST /gasless/submit

Request body of POST /gasless/submit

JSON, required: GaslessSubmitRequest.

Responses of POST /gasless/submit

curl -s -X POST "https://api.qiguard.com/gasless/submit" \
  -H "qg-api-key: $QG_API_KEY" -H "qg-version: v1" \
  -H "content-type: application/json" --data @body.json

body.json is a GaslessSubmitRequest: chainId, and the trade object of your gasless quote unchanged with the signature split into v, r, s.

GET /gasless/status/{tradeHash}

Status of a submitted gasless trade.

Only the app that submitted the trade can read it. confirmed means 5 confirmations on BSC and 3 on Base.

• Key: API key (qg-api-key) and qg-version: v1
• Endpoint id: gasless.status (the name used in the dashboard usage tables)
• Operation id: gasless_getStatus

Parameters of GET /gasless/status/{tradeHash}

Responses of GET /gasless/status/{tradeHash}

curl -s "https://api.qiguard.com/gasless/status/0xa80ae1ca92ebcfd14acb76387a103bd132a66ae86d4292e38550b1d2529e9b10?chainId=8453" \
  -H "qg-api-key: $QG_API_KEY" -H "qg-version: v1"

The example tradeHash is the test-vector digest; use the tradeHash of your own submit.

GET /swap/chains

Chains supported by the Swap endpoints.

• Key: none
• Endpoint id: meta.swap_chains (the name used in the dashboard usage tables)
• Operation id: swap_getChains

Responses of GET /swap/chains

curl -s "https://api.qiguard.com/swap/chains"

Example answer:

{
  "chains": [
    {
      "chainId": 56,
      "chainName": "BSC"
    },
    {
      "chainId": 1,
      "chainName": "Ethereum"
    },
    {
      "chainId": 8453,
      "chainName": "Base"
    },
    {
      "chainId": 137,
      "chainName": "Polygon"
    }
  ],
  "zid": "0x0b7a51f2e9c4d3a8812e6f40"
}

GET /gasless/chains

Chains supported by the Gasless endpoints.

enabled: false means price and quote work but submit returns 503 GASLESS_NOT_ENABLED.

• Key: none
• Endpoint id: meta.gasless_chains (the name used in the dashboard usage tables)
• Operation id: gasless_getChains

Responses of GET /gasless/chains

curl -s "https://api.qiguard.com/gasless/chains"

Example answer:

{
  "chains": [
    {
      "chainId": 56,
      "chainName": "BSC",
      "enabled": false
    },
    {
      "chainId": 8453,
      "chainName": "Base",
      "enabled": false
    }
  ],
  "zid": "0x0b7a51f2e9c4d3a8812e6f40"
}

GET /sources

Liquidity sources of a chain (names usable in excludedSources).

• Key: none
• Endpoint id: meta.sources (the name used in the dashboard usage tables)
• Operation id: sources_getSources

Parameters of GET /sources

Responses of GET /sources

curl -s "https://api.qiguard.com/sources?chainId=56"

Example answer:

{
  "sources": [
    "PancakeSwap_V2",
    "PancakeSwap_V3"
  ],
  "zid": "0x0b7a51f2e9c4d3a8812e6f40"
}

GET /tokens

Tokens and anchors supported on a chain.

• Key: none
• Endpoint id: meta.tokens (the name used in the dashboard usage tables)
• Operation id: tokens_getTokens

Parameters of GET /tokens

Responses of GET /tokens

curl -s "https://api.qiguard.com/tokens?chainId=8453"

GET /status

Live state of every chain (contract pause flag, RPC, swap and gasless availability).

• Key: none
• Endpoint id: meta.status (the name used in the dashboard usage tables)
• Operation id: status_getStatus

Responses of GET /status

curl -s "https://api.qiguard.com/status"

Response headers

Error responses

Every error has the body Error. The full list of names, with the extra data fields, is on the errors page.

Schemas

Schema Address

Type: string, pattern ^0x[0-9a-fA-F]{40}$.

Schema Uint

Unsigned integer as a decimal string.

Type: string, pattern ^[0-9]{1,78}$.

Schema Hex

Type: string, pattern ^0x([0-9a-fA-F]{2})*$.

Schema Bytes32

Type: string, pattern ^0x[0-9a-fA-F]{64}$.

Schema Zid

Request id, 0x + 12 random bytes.

Type: string, pattern ^0x[0-9a-f]{24}$.

Schema Error

{
  "name": "INPUT_INVALID",
  "message": "sellAmount must be a positive integer string",
  "data": {
    "zid": "0x7d1e0c55a9b2f4e83c61d0aa",
    "details": [
      {
        "field": "sellAmount",
        "reason": "not an integer"
      }
    ]
  }
}

Schema Warning

Schema NoLiquidity

Schema QiguardFee

The Qiguard fee of the app's plan (Free 25 bps, paid plans 0), taken on chain from the gross output in the buy token. On a chain without a router it is the settlement fee (USDT-input trades pay it from the sell amount in USDT).

Schema IntegratorFee

One integrator fee (swapFeeRecipient / swapFeeBps), paid on chain to the recipient in the same transaction.

Schema GasFee

Gasless only. In v1 the gas is sponsored, so amount is always "0".

Schema Fees

Schema Issues

Schema RouteFill

Schema Route

One fill per hop. Phase 1 routes use one source for the whole trade, at most 2 hops.

Schema TaxBps

Not measured in v1 (null). Taxed tokens fail simulation and return TOKEN_NOT_SUPPORTED.

Schema TokenMetadata

Schema Transaction

Schema Protection

Schema QiguardCall

Schema SwapPrice

Schema SwapQuote

{
  "liquidityAvailable": true,
  "blockNumber": "129508144",
  "expiresAt": 1793000120,
  "sellToken": "0x55d398326f99059fF775485246999027B3197955",
  "buyToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "sellAmount": "100000000000000000000",
  "buyAmount": "158640000000000000",
  "minBuyAmount": "157053600000000000",
  "allowanceTarget": "0x79A76e54f354AC7567f97d979EC1b785c15e37d8",
  "fees": {
    "integratorFee": null,
    "integratorFees": [],
    "qiguardFee": {
      "amount": "500000000000000000",
      "token": "0x55d398326f99059fF775485246999027B3197955",
      "type": "volume",
      "bps": 50,
      "takenFrom": "sell"
    },
    "gasFee": null
  },
  "issues": {
    "allowance": {
      "actual": "0",
      "spender": "0x79A76e54f354AC7567f97d979EC1b785c15e37d8"
    },
    "balance": null,
    "simulationIncomplete": true,
    "invalidSourcesPassed": []
  },
  "warnings": [],
  "route": {
    "fills": [
      {
        "from": "0x55d398326f99059fF775485246999027B3197955",
        "to": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
        "source": "PancakeSwap_V3",
        "proportionBps": "10000",
        "feeTier": 100
      }
    ],
    "tokens": [
      {
        "address": "0x55d398326f99059fF775485246999027B3197955",
        "symbol": "USDT"
      },
      {
        "address": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
        "symbol": "WBNB"
      }
    ]
  },
  "tokenMetadata": {
    "buyToken": {
      "buyTaxBps": null,
      "sellTaxBps": null,
      "transferTaxBps": null
    },
    "sellToken": {
      "buyTaxBps": null,
      "sellTaxBps": null,
      "transferTaxBps": null
    }
  },
  "totalNetworkFee": "26000000000000",
  "transaction": {
    "to": "0x79A76e54f354AC7567f97d979EC1b785c15e37d8",
    "data": "0x1f60a2c7...71673031a4c2e09b5d7f1e335f1c9a7e2b44",
    "gas": "260000",
    "gasPrice": "100000000",
    "value": "0"
  },
  "protection": {
    "settlementPaused": false,
    "simulation": "skipped_allowance",
    "quoteIntegrity": {
      "rpcAgreement": 2,
      "maxDeviationBps": 4,
      "block": 129508144
    },
    "minBuyAmountEnforcedOnchain": true,
    "priceBand": {
      "onchainEnforced": false,
      "priceImpactBps": 3
    },
    "mev": {
      "submission": "taker_submits"
    }
  },
  "qiguard": {
    "function": "marketSwapTokenToNative",
    "selector": "0x1f60a2c7",
    "adapter": "0xb8dfc084c3912B71662044092722fdDA40b15Ab3",
    "deadline": 1793000120,
    "tag": "0x71673031a4c2e09b5d7f1e335f1c9a7e2b44"
  },
  "mode": "exact-in",
  "zid": "0x5f1c9a7e2b44d0c3a1e8f6b2"
}

Schema PermitWitnessMessage

Schema PermitWitnessTypedData

Must be sent back exactly as returned by /gasless/quote: any change to types, primaryType or domain gives META_TRANSACTION_INVALID. The digest of this object is the tradeHash.

{
  "types": {
    "EIP712Domain": [
      {
        "name": "name",
        "type": "string"
      },
      {
        "name": "chainId",
        "type": "uint256"
      },
      {
        "name": "verifyingContract",
        "type": "address"
      }
    ],
    "PermitWitnessTransferFrom": [
      {
        "name": "permitted",
        "type": "TokenPermissions"
      },
      {
        "name": "spender",
        "type": "address"
      },
      {
        "name": "nonce",
        "type": "uint256"
      },
      {
        "name": "deadline",
        "type": "uint256"
      },
      {
        "name": "witness",
        "type": "OrderWitness"
      }
    ],
    "TokenPermissions": [
      {
        "name": "token",
        "type": "address"
      },
      {
        "name": "amount",
        "type": "uint256"
      }
    ],
    "OrderWitness": [
      {
        "name": "tokenOut",
        "type": "address"
      },
      {
        "name": "minAmountOut",
        "type": "uint256"
      },
      {
        "name": "recipient",
        "type": "address"
      },
      {
        "name": "adapter",
        "type": "address"
      },
      {
        "name": "deadline",
        "type": "uint256"
      }
    ]
  },
  "primaryType": "PermitWitnessTransferFrom",
  "domain": {
    "name": "Permit2",
    "chainId": 8453,
    "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
  },
  "message": {
    "permitted": {
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "25000000"
    },
    "spender": "0x67433187Db1e57f66E88880b6Be833f6759362b1",
    "nonce": "123456789012345678901234567890",
    "deadline": "1793000120",
    "witness": {
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "minAmountOut": "5981940000000000",
      "recipient": "0x1111111111111111111111111111111111111111",
      "adapter": "0xB47011d787B432ccF7A53284a74432a0De4397a3",
      "deadline": "1793000120"
    }
  }
}

Schema Eip712Fields

Type: array of object, items with name, type.

Schema GaslessTrade

Schema GaslessPrice

Schema GaslessQuote

Schema Signature

Schema GaslessSubmitRequest

Schema GaslessSubmitResponse

Schema GaslessStatus

Schema ChainsResponse

Schema GaslessChainsResponse

Schema SourcesResponse

Schema TokensResponse

Schema StatusResponse

This page as Markdown: reference.md. All pages for tools: llms.txt.