From f0c079453b0c2d5eb175942ef8c38e24ca3f38a2 Mon Sep 17 00:00:00 2001 From: Jessica Lin Date: Mon, 14 Sep 2026 12:07:08 -0700 Subject: [PATCH 1/9] Document Arc native token handling Arc uses USDC as both its native gas token and an enshrined ERC-20 at 0x3600000000000000000000000000000000000000. The two identities share one balance but differ in decimals (18 vs 6), so integrators that mix them misprice swaps by 10^12. Adds a section covering the two identities, the decimals footgun, the 20 gwei maxFeePerGas floor, the absence of a wrapped-native token, and wallet/indexer notes (single balance row, duplicate transfer logs, SELFDESTRUCT restrictions). --- .../handling-native-tokens.mdx | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx index 55547e03..b8515955 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx @@ -17,6 +17,10 @@ Mantle’s native token, **MNT**, does not follow this convention. On the Mantle This address applies only to the native `MNT` token on Mantle and should not be used for wrapped or bridged versions on other networks. Refer to the linked guide for additional [differences between Ethereum and Mantle](https://docs.mantle.xyz/network/for-developers/difference-between-ethereum-and-mantle). +#### Arc Exception + +Arc's native gas token is **USDC**, which also exists as an enshrined ERC-20 at `0x3600000000000000000000000000000000000000`. Both identities are accepted by the Swap API, but they use different decimals. See [Arc: USDC as the native gas token](#arc-usdc-as-the-native-gas-token) below before you integrate. + For more context on native token addresses: - [Discussion on native token address](https://www.reddit.com/r/ethereum/comments/iatr1d/what_is_the_significance_of_this_address/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button) @@ -125,3 +129,55 @@ https://api.0x.org/swap/allowance-holder/quote?buyToken=0xEeeeeEeeeEeEeeEeEeEeeE --header '0x-api-key: YOUR_API_KEY' \ --header '0x-version: v2' ``` + +## Arc: USDC as the native gas token + +On Arc, USDC is both the native gas token and an enshrined ERC-20 contract. There is no wrapped-native token, and Circle does not plan to deploy one, so the ETH/WETH pattern described above does not apply. + +### The two identities of USDC + +| | Native USDC | ERC-20 USDC | +| --- | --- | --- | +| Address to pass to 0x | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | `0x3600000000000000000000000000000000000000` | +| Decimals | 18 | 6 | +| How it moves | `msg.value` / account balance | `transfer` / `transferFrom` | +| Allowance required | No | Yes | + +Both identities are backed by a **single balance**. Sending native USDC and transferring ERC-20 USDC move the same money, and the two forms are entangled at the protocol level: an ERC-20 transfer also emits a native transfer. + +### What this means for your integration + + + +Native USDC and ERC-20 USDC differ in scale by a factor of 10^12. `1` USDC is `1000000` in ERC-20 base units and `1000000000000000000` in native base units. Mixing the two misprices a swap by a factor of one trillion. + + + +The Swap API returns amounts in the base units of whichever identity you requested, and performs no conversion between them. Follow these rules: + + + + Use `0x3600000000000000000000000000000000000000` if you want to work in 6 decimals, or `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` if you want to work in 18 decimals. Do not mix the two within a single quote. + + + `sellAmount`, `buyAmount`, `minBuyAmount` and fee amounts are all denominated in the base units of the address you passed. Balance checks, allowance logic and any USD display must use the same decimals. + + + If you requested the ERC-20 identity, the standard ERC-20 flow applies, including an allowance. If you requested the native identity, skip the approval and set `transaction.value`, as described in [Steps for Handling Native Tokens](#steps-for-handling-native-tokens). + + + Arc enforces a 20 gwei floor on `maxFeePerGas`. Transactions submitted below it can stay pending indefinitely or fail outright. A small tip (for example 1 gwei) on `maxPriorityFeePerGas` improves inclusion during high utilization. + + + + + +There is no wrap or unwrap step to build on Arc. A quote between the native and ERC-20 identities of USDC is not a supported swap; move between them by using the interface you need, since they share one balance. + + + +### Notes for wallets and analytics + +- **Show one USDC balance.** Displaying gas balance and USDC balance as separate rows suggests a user holds two assets when they hold one. +- **Expect duplicate transfer logs.** Because the two identities are entangled, a single movement of USDC emits both a native transfer and an ERC-20 `Transfer` event. Indexers that count both will double-count USDC volume. +- **Avoid `SELFDESTRUCT` patterns.** Arc forbids burning USDC, so a self-destructed account cannot receive value-bearing calls. Contracts that rely on `SELFDESTRUCT` can revert in ways that are hard for users to interpret. From ea1c5fe78dc95cc90d60552a6cb5a8950691db06 Mon Sep 17 00:00:00 2001 From: Jessica Lin Date: Mon, 14 Sep 2026 12:12:38 -0700 Subject: [PATCH 2/9] Simplify Arc dual-identity wording --- .../handling-native-tokens.mdx | 40 ++++++++++++------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx index b8515955..94da3954 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx @@ -7,19 +7,21 @@ description: This guide explains how to properly handle native tokens properly i Native tokens are the base currencies of their blockchains—for example, ETH on Ethereum, BNB on BNB Chain, and POL on Polygon. Because native tokens do not have contract addresses like ERC-20 tokens, the placeholder address: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` is commonly used to represent native tokens in blockchain transactions. -### Notes on Native Token Representation +## Conventional Native Token Representation For most of the EVM-compatible chains that we support, the native token is represented using the placeholder address `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. This convention exists because native assets (e.g., ETH on Ethereum) do not have contract addresses like ERC-20 tokens. -#### Mantle Network Exception +## Exceptions + +### Mantle Network Exception Mantle’s native token, **MNT**, does not follow this convention. On the Mantle EVM chain, MNT has a designated contract address: `0xdeaddeaddeaddeaddeaddeaddeaddeaddead0000`. This address applies only to the native `MNT` token on Mantle and should not be used for wrapped or bridged versions on other networks. Refer to the linked guide for additional [differences between Ethereum and Mantle](https://docs.mantle.xyz/network/for-developers/difference-between-ethereum-and-mantle). -#### Arc Exception +### Arc Exception -Arc's native gas token is **USDC**, which also exists as an enshrined ERC-20 at `0x3600000000000000000000000000000000000000`. Both identities are accepted by the Swap API, but they use different decimals. See [Arc: USDC as the native gas token](#arc-usdc-as-the-native-gas-token) below before you integrate. +On Arc, the native gas token is **USDC**. The same USDC is also available as a regular ERC-20 token, built into the chain at `0x3600000000000000000000000000000000000000`. You can trade either one through the Swap API, but each uses a different number of decimals. See [Arc: USDC as the native gas token](#arc-usdc-as-the-native-gas-token) below before you integrate. For more context on native token addresses: @@ -132,16 +134,16 @@ https://api.0x.org/swap/allowance-holder/quote?buyToken=0xEeeeeEeeeEeEeeEeEeEeeE ## Arc: USDC as the native gas token -On Arc, USDC is both the native gas token and an enshrined ERC-20 contract. There is no wrapped-native token, and Circle does not plan to deploy one, so the ETH/WETH pattern described above does not apply. +USDC plays two roles on Arc at once. It is the native gas token, and it is also an ERC-20 token that the chain has built in at a fixed address. There is no wrapped-native token, and Circle does not plan to deploy one, so the ETH/WETH pattern described above does not apply. ### The two identities of USDC -| | Native USDC | ERC-20 USDC | -| --- | --- | --- | +| | Native USDC | ERC-20 USDC | +| --------------------- | -------------------------------------------- | -------------------------------------------- | | Address to pass to 0x | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | `0x3600000000000000000000000000000000000000` | -| Decimals | 18 | 6 | -| How it moves | `msg.value` / account balance | `transfer` / `transferFrom` | -| Allowance required | No | Yes | +| Decimals | 18 | 6 | +| How it moves | `msg.value` / account balance | `transfer` / `transferFrom` | +| Allowance required | No | Yes | Both identities are backed by a **single balance**. Sending native USDC and transferring ERC-20 USDC move the same money, and the two forms are entangled at the protocol level: an ERC-20 transfer also emits a native transfer. @@ -157,16 +159,26 @@ The Swap API returns amounts in the base units of whichever identity you request - Use `0x3600000000000000000000000000000000000000` if you want to work in 6 decimals, or `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` if you want to work in 18 decimals. Do not mix the two within a single quote. + Use `0x3600000000000000000000000000000000000000` if you want to work in 6 + decimals, or `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` if you want to + work in 18 decimals. Do not mix the two within a single quote. - `sellAmount`, `buyAmount`, `minBuyAmount` and fee amounts are all denominated in the base units of the address you passed. Balance checks, allowance logic and any USD display must use the same decimals. + `sellAmount`, `buyAmount`, `minBuyAmount` and fee amounts are all + denominated in the base units of the address you passed. Balance checks, + allowance logic and any USD display must use the same decimals. - If you requested the ERC-20 identity, the standard ERC-20 flow applies, including an allowance. If you requested the native identity, skip the approval and set `transaction.value`, as described in [Steps for Handling Native Tokens](#steps-for-handling-native-tokens). + If you requested the ERC-20 identity, the standard ERC-20 flow applies, + including an allowance. If you requested the native identity, skip the + approval and set `transaction.value`, as described in [Steps for Handling + Native Tokens](#steps-for-handling-native-tokens). - Arc enforces a 20 gwei floor on `maxFeePerGas`. Transactions submitted below it can stay pending indefinitely or fail outright. A small tip (for example 1 gwei) on `maxPriorityFeePerGas` improves inclusion during high utilization. + Arc enforces a 20 gwei floor on `maxFeePerGas`. Transactions submitted below + it can stay pending indefinitely or fail outright. A small tip (for example + 1 gwei) on `maxPriorityFeePerGas` improves inclusion during high + utilization. From 8c1b479c6d45217df0d0eb823133b58ac04a8aaf Mon Sep 17 00:00:00 2001 From: Jessica Lin Date: Mon, 14 Sep 2026 12:14:28 -0700 Subject: [PATCH 3/9] Align Arc USDC table with Arc docs terminology --- .../handling-native-tokens.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx index 94da3954..7c9c6d1a 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx @@ -136,16 +136,16 @@ https://api.0x.org/swap/allowance-holder/quote?buyToken=0xEeeeeEeeeEeEeeEeEeEeeE USDC plays two roles on Arc at once. It is the native gas token, and it is also an ERC-20 token that the chain has built in at a fixed address. There is no wrapped-native token, and Circle does not plan to deploy one, so the ETH/WETH pattern described above does not apply. -### The two identities of USDC +### The two interfaces of USDC -| | Native USDC | ERC-20 USDC | -| --------------------- | -------------------------------------------- | -------------------------------------------- | -| Address to pass to 0x | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | `0x3600000000000000000000000000000000000000` | -| Decimals | 18 | 6 | -| How it moves | `msg.value` / account balance | `transfer` / `transferFrom` | -| Allowance required | No | Yes | +| | Native | ERC-20 | +| --------------------- | ----------------------------------------------------- | ------------------------------------------------------- | +| Address to pass to 0x | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | `0x3600000000000000000000000000000000000000` | +| Decimals | 18 | 6 | +| Purpose | Gas accounting, native sends, and `msg.value` | Application-level transfers, approvals, and allowances | +| Allowance required | No | Yes | -Both identities are backed by a **single balance**. Sending native USDC and transferring ERC-20 USDC move the same money, and the two forms are entangled at the protocol level: an ERC-20 transfer also emits a native transfer. +Both interfaces are backed by a **single balance**. Sending native USDC and transferring ERC-20 USDC move the same money, and the two forms are entangled at the protocol level: an ERC-20 transfer also emits a native transfer. ### What this means for your integration @@ -155,22 +155,22 @@ Native USDC and ERC-20 USDC differ in scale by a factor of 10^12. `1` USDC is `1 -The Swap API returns amounts in the base units of whichever identity you requested, and performs no conversion between them. Follow these rules: +The Swap API returns amounts in the base units of whichever interface you requested, and performs no conversion between them. Follow these rules: - + Use `0x3600000000000000000000000000000000000000` if you want to work in 6 decimals, or `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` if you want to work in 18 decimals. Do not mix the two within a single quote. - + `sellAmount`, `buyAmount`, `minBuyAmount` and fee amounts are all denominated in the base units of the address you passed. Balance checks, allowance logic and any USD display must use the same decimals. - - If you requested the ERC-20 identity, the standard ERC-20 flow applies, - including an allowance. If you requested the native identity, skip the + + If you requested the ERC-20 interface, the standard ERC-20 flow applies, + including an allowance. If you requested the native interface, skip the approval and set `transaction.value`, as described in [Steps for Handling Native Tokens](#steps-for-handling-native-tokens). @@ -184,12 +184,12 @@ The Swap API returns amounts in the base units of whichever identity you request -There is no wrap or unwrap step to build on Arc. A quote between the native and ERC-20 identities of USDC is not a supported swap; move between them by using the interface you need, since they share one balance. +There is no wrap or unwrap step to build on Arc. A quote between the native and ERC-20 interfaces of USDC is not a supported swap; move between them by using the interface you need, since they share one balance. ### Notes for wallets and analytics - **Show one USDC balance.** Displaying gas balance and USDC balance as separate rows suggests a user holds two assets when they hold one. -- **Expect duplicate transfer logs.** Because the two identities are entangled, a single movement of USDC emits both a native transfer and an ERC-20 `Transfer` event. Indexers that count both will double-count USDC volume. +- **Expect duplicate transfer logs.** Because the two interfaces are entangled, a single movement of USDC emits both a native transfer and an ERC-20 `Transfer` event. Indexers that count both will double-count USDC volume. - **Avoid `SELFDESTRUCT` patterns.** Arc forbids burning USDC, so a self-destructed account cannot receive value-bearing calls. Contracts that rely on `SELFDESTRUCT` can revert in ways that are hard for users to interpret. From 0b15c6c89d41fc793166f6f2c64da2fd00bb11fa Mon Sep 17 00:00:00 2001 From: Jessica Lin Date: Mon, 14 Sep 2026 12:26:41 -0700 Subject: [PATCH 4/9] Split chain-specific native token behavior onto its own page Mantle was buried as a subsection of the representation notes and the Arc material had grown into the largest part of the page. Both now live on a Chain-Specific Native Tokens page, leaving the main guide as a single straight-through path: overview, steps, code example, ETH/WETH wrapping. --- fern/docs.yml | 3 + .../chain-specific-native-tokens.mdx | 74 +++++++++++++++++ .../handling-native-tokens.mdx | 79 ++----------------- 3 files changed, 84 insertions(+), 72 deletions(-) create mode 100644 fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx diff --git a/fern/docs.yml b/fern/docs.yml index e4e76436..eb5a8b24 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -214,6 +214,9 @@ navigation: - page: Handle Native Tokens slug: handling-native-tokens path: docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx + - page: Chain-Specific Native Tokens + slug: chain-specific-native-tokens + path: docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx - page: 0x Parser slug: 0x-parser path: docs/pages/0x-swap-api/additional-topics/0x-parser.mdx diff --git a/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx new file mode 100644 index 00000000..f3136583 --- /dev/null +++ b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx @@ -0,0 +1,74 @@ +--- +title: Chain-Specific Native Tokens +description: How to handle native tokens on Mantle and Arc, the chains that do not follow the standard placeholder-address convention. +--- + +Most chains we support represent their native token with the placeholder address `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`, and the flow described in [Handle Native Tokens](/evm/0x-swap-api/additional-topics/handling-native-tokens) applies without changes. This page covers the two chains that behave differently. + +## Mantle: MNT has a contract address + +Mantle’s native token, **MNT**, does not follow this convention. On the Mantle EVM chain, MNT has a designated contract address: `0xdeaddeaddeaddeaddeaddeaddeaddeaddead0000`. + +This address applies only to the native `MNT` token on Mantle and should not be used for wrapped or bridged versions on other networks. Refer to the linked guide for additional [differences between Ethereum and Mantle](https://docs.mantle.xyz/network/for-developers/difference-between-ethereum-and-mantle). + +## Arc: USDC is the native gas token + +USDC plays two roles on Arc at once. It is the native gas token, and it is also an ERC-20 token that the chain has built in at a fixed address. There is no wrapped-native token, and Circle does not plan to deploy one, so the [ETH/WETH wrapping pattern](/evm/0x-swap-api/additional-topics/handling-native-tokens#wrapping-and-unwrapping-between-eth-and-weth) does not apply. + +### The two interfaces of USDC + +| | Native | ERC-20 | +| --------------------- | --------------------------------------------- | ------------------------------------------------------ | +| Address to pass to 0x | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | `0x3600000000000000000000000000000000000000` | +| Decimals | 18 | 6 | +| Purpose | Gas accounting, native sends, and `msg.value` | Application-level transfers, approvals, and allowances | +| Allowance required | No | Yes | + +Both interfaces are backed by a **single balance**. Sending native USDC and transferring ERC-20 USDC move the same money, and the two forms are entangled at the protocol level: an ERC-20 transfer also emits a native transfer. + +### What this means for your integration + + + +Native USDC and ERC-20 USDC differ in scale by a factor of 10^12. `1` USDC is `1000000` in ERC-20 base units and `1000000000000000000` in native base units. Mixing the two misprices a swap by a factor of one trillion. + + + +The Swap API returns amounts in the base units of whichever interface you requested, and performs no conversion between them. Follow these rules: + + + + Use `0x3600000000000000000000000000000000000000` if you want to work in 6 + decimals, or `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` if you want to + work in 18 decimals. Do not mix the two within a single quote. + + + `sellAmount`, `buyAmount`, `minBuyAmount` and fee amounts are all + denominated in the base units of the address you passed. Balance checks, + allowance logic and any USD display must use the same decimals. + + + If you requested the ERC-20 interface, the standard ERC-20 flow applies, + including an allowance. If you requested the native interface, skip the + approval and set `transaction.value`, as described in [Handle Native + Tokens](/evm/0x-swap-api/additional-topics/handling-native-tokens#steps-for-handling-standard-native-tokens). + + + Arc enforces a 20 gwei floor on `maxFeePerGas`. Transactions submitted below + it can stay pending indefinitely or fail outright. A small tip (for example + 1 gwei) on `maxPriorityFeePerGas` improves inclusion during high + utilization. + + + + + +There is no wrap or unwrap step to build on Arc. A quote between the native and ERC-20 interfaces of USDC is not a supported swap; move between them by using the interface you need, since they share one balance. + + + +### Notes for wallets and analytics + +- **Show one USDC balance.** Displaying gas balance and USDC balance as separate rows suggests a user holds two assets when they hold one. +- **Expect duplicate transfer logs.** Because the two interfaces are entangled, a single movement of USDC emits both a native transfer and an ERC-20 `Transfer` event. Indexers that count both will double-count USDC volume. +- **Avoid `SELFDESTRUCT` patterns.** Arc forbids burning USDC, so a self-destructed account cannot receive value-bearing calls. Contracts that rely on `SELFDESTRUCT` can revert in ways that are hard for users to interpret. diff --git a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx index 7c9c6d1a..41a19ec5 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx @@ -7,28 +7,25 @@ description: This guide explains how to properly handle native tokens properly i Native tokens are the base currencies of their blockchains—for example, ETH on Ethereum, BNB on BNB Chain, and POL on Polygon. Because native tokens do not have contract addresses like ERC-20 tokens, the placeholder address: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` is commonly used to represent native tokens in blockchain transactions. -## Conventional Native Token Representation +## Standard Native Token Representation For most of the EVM-compatible chains that we support, the native token is represented using the placeholder address `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. This convention exists because native assets (e.g., ETH on Ethereum) do not have contract addresses like ERC-20 tokens. -## Exceptions +## Chain-Specific Exceptions -### Mantle Network Exception +Two chains we support do not follow this convention: -Mantle’s native token, **MNT**, does not follow this convention. On the Mantle EVM chain, MNT has a designated contract address: `0xdeaddeaddeaddeaddeaddeaddeaddeaddead0000`. +- **Mantle** uses a designated contract address for its native token, MNT. +- **Arc** uses USDC as its native gas token, exposed through two interfaces that use different decimals. -This address applies only to the native `MNT` token on Mantle and should not be used for wrapped or bridged versions on other networks. Refer to the linked guide for additional [differences between Ethereum and Mantle](https://docs.mantle.xyz/network/for-developers/difference-between-ethereum-and-mantle). - -### Arc Exception - -On Arc, the native gas token is **USDC**. The same USDC is also available as a regular ERC-20 token, built into the chain at `0x3600000000000000000000000000000000000000`. You can trade either one through the Swap API, but each uses a different number of decimals. See [Arc: USDC as the native gas token](#arc-usdc-as-the-native-gas-token) below before you integrate. +Before integrating on either, read [Chain-Specific Native Tokens](/evm/0x-swap-api/additional-topics/chain-specific-native-tokens). For more context on native token addresses: - [Discussion on native token address](https://www.reddit.com/r/ethereum/comments/iatr1d/what_is_the_significance_of_this_address/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button) - [Stack Exchange explanation](https://ethereum.stackexchange.com/a/87444/85979). -## Steps for Handling Native Tokens +## Steps for Handling Standard Native Tokens @@ -131,65 +128,3 @@ https://api.0x.org/swap/allowance-holder/quote?buyToken=0xEeeeeEeeeEeEeeEeEeEeeE --header '0x-api-key: YOUR_API_KEY' \ --header '0x-version: v2' ``` - -## Arc: USDC as the native gas token - -USDC plays two roles on Arc at once. It is the native gas token, and it is also an ERC-20 token that the chain has built in at a fixed address. There is no wrapped-native token, and Circle does not plan to deploy one, so the ETH/WETH pattern described above does not apply. - -### The two interfaces of USDC - -| | Native | ERC-20 | -| --------------------- | ----------------------------------------------------- | ------------------------------------------------------- | -| Address to pass to 0x | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | `0x3600000000000000000000000000000000000000` | -| Decimals | 18 | 6 | -| Purpose | Gas accounting, native sends, and `msg.value` | Application-level transfers, approvals, and allowances | -| Allowance required | No | Yes | - -Both interfaces are backed by a **single balance**. Sending native USDC and transferring ERC-20 USDC move the same money, and the two forms are entangled at the protocol level: an ERC-20 transfer also emits a native transfer. - -### What this means for your integration - - - -Native USDC and ERC-20 USDC differ in scale by a factor of 10^12. `1` USDC is `1000000` in ERC-20 base units and `1000000000000000000` in native base units. Mixing the two misprices a swap by a factor of one trillion. - - - -The Swap API returns amounts in the base units of whichever interface you requested, and performs no conversion between them. Follow these rules: - - - - Use `0x3600000000000000000000000000000000000000` if you want to work in 6 - decimals, or `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` if you want to - work in 18 decimals. Do not mix the two within a single quote. - - - `sellAmount`, `buyAmount`, `minBuyAmount` and fee amounts are all - denominated in the base units of the address you passed. Balance checks, - allowance logic and any USD display must use the same decimals. - - - If you requested the ERC-20 interface, the standard ERC-20 flow applies, - including an allowance. If you requested the native interface, skip the - approval and set `transaction.value`, as described in [Steps for Handling - Native Tokens](#steps-for-handling-native-tokens). - - - Arc enforces a 20 gwei floor on `maxFeePerGas`. Transactions submitted below - it can stay pending indefinitely or fail outright. A small tip (for example - 1 gwei) on `maxPriorityFeePerGas` improves inclusion during high - utilization. - - - - - -There is no wrap or unwrap step to build on Arc. A quote between the native and ERC-20 interfaces of USDC is not a supported swap; move between them by using the interface you need, since they share one balance. - - - -### Notes for wallets and analytics - -- **Show one USDC balance.** Displaying gas balance and USDC balance as separate rows suggests a user holds two assets when they hold one. -- **Expect duplicate transfer logs.** Because the two interfaces are entangled, a single movement of USDC emits both a native transfer and an ERC-20 `Transfer` event. Indexers that count both will double-count USDC volume. -- **Avoid `SELFDESTRUCT` patterns.** Arc forbids burning USDC, so a self-destructed account cannot receive value-bearing calls. Contracts that rely on `SELFDESTRUCT` can revert in ways that are hard for users to interpret. From 8749d29be92b08ca0891128740a6a0647efaa9f4 Mon Sep 17 00:00:00 2001 From: Jessica Lin Date: Mon, 14 Sep 2026 12:33:16 -0700 Subject: [PATCH 5/9] Match Arc USDC table layout to Arc docs --- .../chain-specific-native-tokens.mdx | 12 +++++------- .../additional-topics/handling-native-tokens.mdx | 6 ++++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx index f3136583..5909991e 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx @@ -5,7 +5,7 @@ description: How to handle native tokens on Mantle and Arc, the chains that do n Most chains we support represent their native token with the placeholder address `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`, and the flow described in [Handle Native Tokens](/evm/0x-swap-api/additional-topics/handling-native-tokens) applies without changes. This page covers the two chains that behave differently. -## Mantle: MNT has a contract address +## Mantle: MNT is the native gas token Mantle’s native token, **MNT**, does not follow this convention. On the Mantle EVM chain, MNT has a designated contract address: `0xdeaddeaddeaddeaddeaddeaddeaddeaddead0000`. @@ -17,12 +17,10 @@ USDC plays two roles on Arc at once. It is the native gas token, and it is also ### The two interfaces of USDC -| | Native | ERC-20 | -| --------------------- | --------------------------------------------- | ------------------------------------------------------ | -| Address to pass to 0x | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | `0x3600000000000000000000000000000000000000` | -| Decimals | 18 | 6 | -| Purpose | Gas accounting, native sends, and `msg.value` | Application-level transfers, approvals, and allowances | -| Allowance required | No | Yes | +| Interface | Decimals | Purpose | Address to pass to 0x | +| --------- | -------- | ------------------------------------------------------ | -------------------------------------------- | +| Native | 18 | Gas accounting, native sends, and `msg.value` | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | +| ERC-20 | 6 | Application-level transfers, approvals, and allowances | `0x3600000000000000000000000000000000000000` | Both interfaces are backed by a **single balance**. Sending native USDC and transferring ERC-20 USDC move the same money, and the two forms are entangled at the protocol level: an ERC-20 transfer also emits a native transfer. diff --git a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx index 41a19ec5..a8fe9a1e 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx @@ -15,11 +15,13 @@ For most of the EVM-compatible chains that we support, the native token is repre Two chains we support do not follow this convention: -- **Mantle** uses a designated contract address for its native token, MNT. -- **Arc** uses USDC as its native gas token, exposed through two interfaces that use different decimals. +- **Mantle** uses a designated contract address for its native token, **MNT**. +- **Arc** uses **USDC** as its native gas token, exposed through two interfaces that use different decimals. Before integrating on either, read [Chain-Specific Native Tokens](/evm/0x-swap-api/additional-topics/chain-specific-native-tokens). +## Additional Resources + For more context on native token addresses: - [Discussion on native token address](https://www.reddit.com/r/ethereum/comments/iatr1d/what_is_the_significance_of_this_address/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button) From 98b78dccc77a3804fb944633fe26c85f5de2dac8 Mon Sep 17 00:00:00 2001 From: Jessica Lin Date: Mon, 14 Sep 2026 12:35:27 -0700 Subject: [PATCH 6/9] Revert "Match Arc USDC table layout to Arc docs" This reverts commit 8749d29be92b08ca0891128740a6a0647efaa9f4. --- .../chain-specific-native-tokens.mdx | 12 +++++++----- .../additional-topics/handling-native-tokens.mdx | 6 ++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx index 5909991e..f3136583 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx @@ -5,7 +5,7 @@ description: How to handle native tokens on Mantle and Arc, the chains that do n Most chains we support represent their native token with the placeholder address `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`, and the flow described in [Handle Native Tokens](/evm/0x-swap-api/additional-topics/handling-native-tokens) applies without changes. This page covers the two chains that behave differently. -## Mantle: MNT is the native gas token +## Mantle: MNT has a contract address Mantle’s native token, **MNT**, does not follow this convention. On the Mantle EVM chain, MNT has a designated contract address: `0xdeaddeaddeaddeaddeaddeaddeaddeaddead0000`. @@ -17,10 +17,12 @@ USDC plays two roles on Arc at once. It is the native gas token, and it is also ### The two interfaces of USDC -| Interface | Decimals | Purpose | Address to pass to 0x | -| --------- | -------- | ------------------------------------------------------ | -------------------------------------------- | -| Native | 18 | Gas accounting, native sends, and `msg.value` | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | -| ERC-20 | 6 | Application-level transfers, approvals, and allowances | `0x3600000000000000000000000000000000000000` | +| | Native | ERC-20 | +| --------------------- | --------------------------------------------- | ------------------------------------------------------ | +| Address to pass to 0x | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | `0x3600000000000000000000000000000000000000` | +| Decimals | 18 | 6 | +| Purpose | Gas accounting, native sends, and `msg.value` | Application-level transfers, approvals, and allowances | +| Allowance required | No | Yes | Both interfaces are backed by a **single balance**. Sending native USDC and transferring ERC-20 USDC move the same money, and the two forms are entangled at the protocol level: an ERC-20 transfer also emits a native transfer. diff --git a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx index a8fe9a1e..41a19ec5 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx @@ -15,13 +15,11 @@ For most of the EVM-compatible chains that we support, the native token is repre Two chains we support do not follow this convention: -- **Mantle** uses a designated contract address for its native token, **MNT**. -- **Arc** uses **USDC** as its native gas token, exposed through two interfaces that use different decimals. +- **Mantle** uses a designated contract address for its native token, MNT. +- **Arc** uses USDC as its native gas token, exposed through two interfaces that use different decimals. Before integrating on either, read [Chain-Specific Native Tokens](/evm/0x-swap-api/additional-topics/chain-specific-native-tokens). -## Additional Resources - For more context on native token addresses: - [Discussion on native token address](https://www.reddit.com/r/ethereum/comments/iatr1d/what_is_the_significance_of_this_address/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button) From 4c75729fa995635e1ee26d73aadfdca8c02cc1f6 Mon Sep 17 00:00:00 2001 From: Jessica Lin Date: Mon, 14 Sep 2026 12:35:45 -0700 Subject: [PATCH 7/9] Restore Additional Resources heading and bold token names --- .../additional-topics/handling-native-tokens.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx index 41a19ec5..a8fe9a1e 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/handling-native-tokens.mdx @@ -15,11 +15,13 @@ For most of the EVM-compatible chains that we support, the native token is repre Two chains we support do not follow this convention: -- **Mantle** uses a designated contract address for its native token, MNT. -- **Arc** uses USDC as its native gas token, exposed through two interfaces that use different decimals. +- **Mantle** uses a designated contract address for its native token, **MNT**. +- **Arc** uses **USDC** as its native gas token, exposed through two interfaces that use different decimals. Before integrating on either, read [Chain-Specific Native Tokens](/evm/0x-swap-api/additional-topics/chain-specific-native-tokens). +## Additional Resources + For more context on native token addresses: - [Discussion on native token address](https://www.reddit.com/r/ethereum/comments/iatr1d/what_is_the_significance_of_this_address/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button) From d918f042e93fa7e7f70aa88313099772401fb0d9 Mon Sep 17 00:00:00 2001 From: Jessica Lin Date: Mon, 14 Sep 2026 12:37:11 -0700 Subject: [PATCH 8/9] Link to Arc's stablecoin-native model docs --- .../additional-topics/chain-specific-native-tokens.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx index f3136583..acf75748 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx @@ -13,7 +13,7 @@ This address applies only to the native `MNT` token on Mantle and should not be ## Arc: USDC is the native gas token -USDC plays two roles on Arc at once. It is the native gas token, and it is also an ERC-20 token that the chain has built in at a fixed address. There is no wrapped-native token, and Circle does not plan to deploy one, so the [ETH/WETH wrapping pattern](/evm/0x-swap-api/additional-topics/handling-native-tokens#wrapping-and-unwrapping-between-eth-and-weth) does not apply. +USDC plays two roles on Arc at once. It is the native gas token, and it is also an ERC-20 token that the chain has built in at a fixed address. There is no wrapped-native token, and Circle does not plan to deploy one, so the [ETH/WETH wrapping pattern](/evm/0x-swap-api/additional-topics/handling-native-tokens#wrapping-and-unwrapping-between-eth-and-weth) does not apply. Refer to Arc's own guide for the full details of [USDC as the native gas token](https://docs.arc.io/arc/concepts/stablecoin-native-model#usdc-as-the-native-gas-token). ### The two interfaces of USDC From 75ac708726db181754ec82c2aa6332daadb11079 Mon Sep 17 00:00:00 2001 From: Jessica Lin Date: Tue, 15 Sep 2026 18:39:40 -0700 Subject: [PATCH 9/9] clarify Arc USDC unit example and duplicate transfer logs --- .../additional-topics/chain-specific-native-tokens.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx index acf75748..7aa75121 100644 --- a/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx +++ b/fern/docs/pages/0x-swap-api/additional-topics/chain-specific-native-tokens.mdx @@ -30,7 +30,7 @@ Both interfaces are backed by a **single balance**. Sending native USDC and tran -Native USDC and ERC-20 USDC differ in scale by a factor of 10^12. `1` USDC is `1000000` in ERC-20 base units and `1000000000000000000` in native base units. Mixing the two misprices a swap by a factor of one trillion. +Native USDC and ERC-20 USDC differ in scale by a factor of 10^12. One whole USDC ($1.00) is `1000000` in ERC-20 base units and `1000000000000000000` in native base units. Mixing the two misprices a swap by a factor of one trillion. @@ -70,5 +70,5 @@ There is no wrap or unwrap step to build on Arc. A quote between the native and ### Notes for wallets and analytics - **Show one USDC balance.** Displaying gas balance and USDC balance as separate rows suggests a user holds two assets when they hold one. -- **Expect duplicate transfer logs.** Because the two interfaces are entangled, a single movement of USDC emits both a native transfer and an ERC-20 `Transfer` event. Indexers that count both will double-count USDC volume. +- **Expect duplicate transfer logs on ERC-20 moves only.** Moving USDC through the ERC-20 interface emits both a native transfer and an ERC-20 `Transfer` event, so indexers that count both will double-count USDC volume. Moving it through the native interface emits a single log. - **Avoid `SELFDESTRUCT` patterns.** Arc forbids burning USDC, so a self-destructed account cannot receive value-bearing calls. Contracts that rely on `SELFDESTRUCT` can revert in ways that are hard for users to interpret.