Integration engineering

Native token sentinel addresses need provider adapters

Translate native currency through a provider-specific adapter rather than assuming one placeholder address works everywhere.

A native-token sentinel is an API convention, not a deployed ERC-20 contract. Keep native currency distinct inside your application and translate it only when creating a particular provider request.

Verified examples differ

InterfaceNative representation
PancakeSwap Unified Swap quoteZero address
0x Swap API common EVM convention0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
OKX DEX quote documentation0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

These conventions come from the PancakeSwap endpoint reference, 0x API issue reference and OKX quote reference, checked for this publication. Apply them only to those documented interfaces.

Chain exceptions still need explicit handling. The 0x FAQ documents a different representation for native MNT on Mantle. Therefore, key native mappings by provider, interface version and chain; do not let a shared EVM default override a documented chain-specific value.

Avoid three category errors

Do not call decimals or allowance on a sentinel. Do not replace native BNB with WBNB merely because both are economically related. Do not send funds directly to the placeholder address. Wrapping, unwrapping and transaction funding are execution actions whose payload must come from the supported route.

A proposed adapter can map an internal object such as kind:native, chainId:56 into each API's required value. The reverse mapping matters too: decode a provider's native marker back into your native type before displaying metadata or deciding whether approval is needed.

Test native input and native output independently. Native input requires correct transaction value and a gas reserve. Native output requires correct receipt reconciliation; an ERC-20 Transfer event is not always the evidence you need. A wrapped-token fixture should remain an ordinary contract-token fixture even when its symbol resembles the native asset.

Sources & verification (4)

Source-check date is recorded in the article details. URLs are provided for manual verification. Use Copy to keep this page open.

  1. Endpoints

    Quote, calldata, submit and status contracts

    https://developer.pancakeswap.finance/contracts/unified-swap-api/endpoints
  2. Issues & Error Codes

    Distinct allowance, balance and incomplete simulation issues

    https://docs.0x.org/docs/introduction/api-issues
  3. Get Quotes

    v6 quote schema, chainIndex, amount units and native sentinel

    https://web3.okx.com/onchainos/dev-docs/trade/dex-get-quote
  4. 0x FAQ

    Native asset convention and Mantle MNT exception

    https://docs.0x.org/docs/introduction/faq

Continue reading

Swap API integration: quote, approve, simulate, submit