Production Readiness - Coinbase Developer Documentation

Everything you need for production swaps.

Best practices

Token decimals

The program supports tokens with different decimal precision. Amounts are automatically normalized during swaps so equivalent values are preserved across different decimal precisions.

Ethereum Virtual Machine
Solana Virtual Machine

EVM tokens commonly use 6 decimals (USDC) or 18 decimals. The contract normalizes between them automatically.

// Example: expressing 100 tokens for a 6-decimal token (e.g., USDC)
const amount = ethers.parseUnits("100", 6);

// Example: expressing 100 tokens for an 18-decimal token
const amount18 = ethers.parseUnits("100", 18);

You can query a token’s decimals from the contract:

const decimals = await stableSwapper.getTokenDecimals(tokenAddress);

Solana tokens typically use 6 to 9 decimals.

// Example: expressing 100 tokens for a 6-decimal token
const amount = 100 * Math.pow(10, 6); // = 100_000_000

// Using anchor.BN for large numbers
const amountBN = new anchor.BN(100 * 10 ** 6);

Slippage protection

Always set minAmountOut to protect against fee rate changes between when you construct the transaction and when it executes.

Ethereum Virtual Machine
Solana Virtual Machine

// Read fee from contract and calculate expected output
const feeBps = await stableSwapper.feeBasisPoints();
const amountIn = ethers.parseUnits("100", 6);

// Fee is charged on the input token, rounded up
const fee = (amountIn * BigInt(feeBps) + 9999n) / 10000n;
const expectedOutput = amountIn - fee;

// Apply slippage tolerance (2%)
const slippageBps = 200n;
const minAmountOut = expectedOutput * (10000n - slippageBps) / 10000n;

// Calculate slippage tolerance
const expectedOutput = new anchor.BN(100 * 10 ** 6);
const slippageTolerance = 0.02; // 2%
const minAmountOut = expectedOutput.muln(1 - slippageTolerance);

// Or use the helper function
const { amountOut, fee } = await calculateSwapOutput(amountIn);
const minAmountOut = amountOut.muln(0.98); // Allow 2% variance

Allowlist

The allowlist may be enabled for this pool. When active, only allowlisted addresses can execute swaps. Transactions from non-allowlisted addresses will fail. Contact your integration partner to be added to the allowlist.

Ethereum Virtual Machine
Solana Virtual Machine

For smart contract integrations: The calling contract’s address (msg.sender) must be allowlisted, not the EOA that initiated the outer transaction. You can check allowlist status before sending a transaction:

const allowlistEnabled = await stableSwapper.isFeatureEnabled(2); // 2 = ALLOWLIST
if (allowlistEnabled) {
  const isAllowed = await stableSwapper.isAllowlisted(walletAddress);
  if (!isAllowed) {
    throw new Error("Address not allowlisted");
  }
}

For smart contract integrations via CPI (Cross-Program Invocation): The PDA address (not its token accounts) must be whitelisted. Ensure the PDA has sufficient SOL to cover potential account creation fees when calling via invoke_signed.

ERC-20 approvals (Base only)

Before swapping on Base, the Stableswapper contract must be approved to transfer your input tokens. This is a standard ERC-20 requirement.

const token = new ethers.Contract(tokenInAddress, ERC20_ABI, signer);

// Option 1: Approve exact amount (most secure, requires approval per swap)
await token.approve(STABLESWAPPER_ADDRESS, amountIn);

// Option 2: Approve a larger amount to avoid repeated approvals
await token.approve(STABLESWAPPER_ADDRESS, ethers.MaxUint256);

Approving MaxUint256 is convenient but gives the contract unlimited spending authority over that token. For production, consider approving exact amounts or using a reasonable upper bound.

Security considerations

Always verify addresses

Verify the contract address before sending transactions — use the address from the Key Addresses page
Double-check token addresses — confirm both input and output token addresses against the Key Addresses page
Validate user inputs — sanitize and bounds-check all amounts and addresses

Test thoroughly

Test on devnet/testnet first with small amounts
Run integration tests covering success and failure cases
Test edge cases like zero amounts, maximum amounts, and missing accounts or approvals

Handle failures gracefully

Never assume success — always check transaction results
Provide clear error messages to users
Implement retry logic for network failures (but not for validation errors)

Monitor transactions

Log transaction signatures/hashes for debugging and support
Track failed transactions to identify patterns
Monitor pool liquidity to warn users before failures

Pre-flight checklist

Before sending a swap on mainnet, verify:

Ethereum Virtual Machine
Solana Virtual Machine

User has sufficient input token balance
User has sufficient ETH for gas fees
ERC-20 approval is set for the Stableswapper contract on the input token
Both tokens are listed and swappable
Swap feature is enabled
Contract has sufficient output token liquidity (balance minus reserved amount)
User address is allowlisted (if allowlist feature is enabled)
Slippage tolerance accounts for current fee rate
Contract address and token addresses match the Key Addresses page

See Key Addresses for all contract and token addresses.

Troubleshooting

Common errors and solutions

Examples

Code samples for common scenarios

Reference

Swap instruction parameters

Quickstart

Get up and running in 10 minutes

​Best practices

​Token decimals

​Slippage protection

​Allowlist

​ERC-20 approvals (Base only)

​Security considerations

​Pre-flight checklist

​What to read next

Troubleshooting

Examples

Reference

Quickstart

Best practices

Token decimals

Slippage protection

Allowlist

ERC-20 approvals (Base only)

Security considerations

Pre-flight checklist

What to read next