Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.portalhq.io/llms.txt

Use this file to discover all available pages before exploring further.

Portal’s Web SDK provides high-level 0x swaps through portal.trading.zeroX.tradeAsset(...) and lower-level access through portal.trading.zeroX.

​
Overview

Using the 0x integration, you can:
  • Trade assets end-to-end with one high-level call
  • Track lifecycle progress from quote fetch to confirmation
  • Override signer and confirmation behavior per call when needed
  • Fetch indicative prices for token swaps
  • Fetch swap quotes between supported tokens
  • Retrieve available liquidity sources
  • Execute swaps manually by signing and submitting transactions from a quote

​
Prerequisites

Before using the 0x API, make sure you have:
  • A properly initialized Portal client
  • An active wallet with sufficient balance on the source network
    (see Create a wallet)
  • 0x integration enabled in your Portal Dashboard (see 0x Integration) OR have a 0x API Key available

​
High-Level Methods

​
tradeAsset

Fetches a 0x quote, signs and broadcasts the quote transaction, waits for on-chain confirmation, and returns hashes.

​
Signature

tradeAsset(
  params: ZeroXTradeAssetParams,
  options?: ZeroXTradeAssetOptions & ZeroExOptions,
): Promise<ZeroXTradeAssetResult>
Essential parameters
NameRequiredDescription
chainIdYesCAIP-2 chain (e.g. 'eip155:1'). See Supported Networks.
sellTokenYesToken to sell (symbol or address).
buyTokenYesToken to buy (symbol or address).
sellAmountYesAmount in base units (smallest units).
fromAddressYesSender address used by high-level 0x execution (use this field, not txOrigin).
slippageBpsNoMax slippage in basis points (e.g. 100 = 1%).
swapFeeRecipient, swapFeeBps, swapFeeTokenNoIntegrator fee fields.
tradeSurplusRecipientNoSurplus recipient.
gasPriceNoOptional gas price.
excludedSourcesNoComma-separated sources to exclude.
sellEntireBalanceNo'true' / 'false'.
onProgressNoStages such as fetching_quote, signing, submitted, confirming, confirmed, failed.
zeroXApiKeyNoOverride the Dashboard key for this call.
ZeroXTradeAssetOptions:
NameRequiredDescription
signAndSendTransactionNoPer-call signer override.
waitForConfirmationNoPer-call confirmation override. MUST return true or resolve for success. Returning false, throwing an error, or timing out will abort the swap and throw an error.
evmRequestFnNoWeb SDK: When waitForConfirmation is omitted, receipt polling can use this JSON-RPC function (e.g. eth_getTransactionReceipt) on EVM chains.
evmPollerOptionsNoTune the built-in EVM receipt poller when using evmRequestFn (pollIntervalMs, timeoutMs).
(Inherited from ZeroExOptions) zeroXApiKeyNoPer-call API key (overrides Dashboard key).
Return value
FieldDescription
hashesBroadcast transaction hashes.
0x tradeAsset execution precedence:
  • Signer: per-call options.signAndSendTransaction → instance default signer → throw
  • Confirmation: per-call options.waitForConfirmation → instance default waiter, or on Web, evmRequestFn + receipt polling when waitForConfirmation is omitted
Confirmation is strict: if the waiter returns false, times out, throws an error, or the network is unsupported, the swap fails immediately and throws.On portal-react-native, tradeAsset does not offer evmRequestFn; you supply waitForConfirmation (or rely on the Portal default where wired).
tradeAsset requires at least one confirmation mechanism. If neither waitForConfirmation nor evmRequestFn is available (from instance defaults or per-call options), the method throws immediately:[ZeroX] tradeAsset requires waitForConfirmation (instance default or per-call option), or evmRequestFn fallback.When you construct Portal with an rpcConfig, evmRequestFn is wired automatically — no extra setup needed. This requirement only surfaces when using ZeroX standalone or without Portal’s default wiring.Receipt-polling timeouts are strict: if confirmation times out, the swap throws and does not return a result.
Example (onProgress + default on-chain wait) 
import Portal from '@portal-hq/web'
import type { ZeroXTradeAssetParams } from '@portal-hq/web'

const portal = new Portal({
  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
  rpcConfig: {
    'eip155:1': 'https://YOUR_RPC_URL',
  },
})

async function swap() {
  const eip155Address = await portal.getEip155Address()
  if (!eip155Address) throw new Error('No EVM address')

  const params: ZeroXTradeAssetParams = {
    chainId: 'eip155:1',
    sellToken: 'ETH',
    buyToken: 'USDC',
    sellAmount: '100000000000000',
    fromAddress: eip155Address,
    onProgress: (status, data) => {
      console.log('[0x]', status, data?.txHash ?? '', data?.errorMessage ?? '')
    },
  }

  try {
    const result = await portal.trading.zeroX.tradeAsset(params)
    console.log('Hashes:', result.hashes)
    return result
  } catch (e) {
    console.error('tradeAsset failed', e)
    throw e
  }
}
Use try/catch around tradeAsset; onProgress may emit failed before the thrown error.

​
Example (custom API key + execution options)

const eip155Address = await portal.getEip155Address()
if (!eip155Address) throw new Error('No EVM address')

const result = await portal.trading.zeroX.tradeAsset(
  {
    chainId: 'eip155:1',
    sellToken: 'ETH',
    buyToken: 'USDC',
    sellAmount: '100000000000000',
    fromAddress: eip155Address,
    zeroXApiKey: 'YOUR_0X_API_KEY',
    onProgress: (status, data) => {
      console.log('[0x]', status, data?.txHash ?? '', data?.errorMessage ?? '')
    },
  },
  {
    waitForConfirmation: async (txHash, network) => {
      return portal.waitForConfirmation(txHash, network)
    },
  },
)

console.log(result.hashes)

​
Low-level methods

The following methods return quotes, prices, or raw transaction data for you to sign with portal.request when you need full control over each step.

​
Using a Custom 0x API Key (Optional)

By default, Portal uses the 0x API Key that can be added through the Portal Dashboard to communicate with the 0x integration. If you have a 0x API key that you want to test with locally, you can optionally include it in the request body via the options parameter. 
await portal.trading.zeroX.getQuote(request)

await portal.trading.zeroX.getQuote(request, {
  zeroXApiKey: 'YOUR_0X_API_KEY',
})

​
Getting a Price (Indicative)

Use portal.trading.zeroX.getPrice to retrieve an indicative price for a token swap without generating executable transaction data. This method is useful for displaying prices, estimating swap outcomes, or building preview experiences without committing to a quote. 
async function getZeroXPrice(portal: Portal) {
  const request: ZeroExPriceRequest = {
    chainId: 'eip155:8453', // BASE network
    sellToken: 'ETH',
    buyToken: 'USDC',
    sellAmount: '10000000000000', // 0.00001 ETH
  }

  const response = await portal.trading.zeroX.getPrice(request)
  const price = response.data.rawResponse
}

​
Getting a Swap Quote

Use portal.trading.zeroX.getQuote to fetch a swap quote from 0x. 
async function getZeroXQuote(portal: Portal) {
  const takerAddress = await portal.getEip155Address()

  const request: ZeroExQuoteRequest = {
    chainId: 'eip155:8453', // BASE network
    sellToken: 'ETH',
    buyToken: 'USDC',
    sellAmount: '10000000000000', // 0.00001 ETH
  }

  const response = await portal.trading.zeroX.getQuote(request)
  const quote = response.data.rawResponse

  console.log(quote)
}

​
Getting Liquidity Sources

You can query available liquidity sources supported by 0x using portal.trading.zeroX.getSources. For full request and response details, refer to the Client API documentation. 
async function getZeroXSources(portal: Portal) {
  const response = await portal.trading.zeroX.getSources('eip155:1')

  const sources = response.data.rawResponse
}

​
Low-level: Executing the Swap

Once you receive a quote containing transaction data, execute the swap by sending the transaction through portal.request.
Note
The transaction data returned by 0x may include gas parameters such as gas or gasPrice. These fields are optional — you can omit them and let Portal estimate gas automatically, or include them if you prefer to use 0x’s suggested values. 
async function executeSwap(
  portal: Portal,
  fromAddress: string,
  quoteResponse: ZeroExQuoteResponse,
  chainId: string
) {
  const ethTx: ETHTransactionParam = {
    from: fromAddress,
    to: quoteResponse.data?.rawResponse.transaction.to,
    value: quoteResponse.data?.rawResponse.transaction.value ?? '0x0',
    data: quoteResponse.data?.rawResponse.transaction.data,
  }

  const response = await portal.request({ chainId, method: 'eth_sendTransaction', params: [ethTx] })
}

​
Supported Networks

The portal.trading.zeroX API supports a predefined set of EIP-155 networks. Requests using unsupported chains will fail.
NetworkEIP-155 Chain ID
Ethereumeip155:1
Optimismeip155:10
BSCeip155:56
Unichaineip155:130
Polygoneip155:137
Worldchaineip155:480
Mantleeip155:5000
Baseeip155:8453
Monad Testneteip155:10143
Modeeip155:34443
Arbitrumeip155:42161
Avalancheeip155:43114
Inkeip155:57073
Lineaeip155:59144
Berachaineip155:80094
Blasteip155:81457
Scrolleip155:534352

​
Next Steps