EVM allowance

Understand EVM allowance methods for Omniston and choose between EIP-2612, Permit2, and native ERC-20 approve.

This document is the main entry point for choosing the right EVM allowance method for an Omniston integration.

It answers two questions:

1. Which allowance method should an integrator use for a given token or product flow?

2. Once that allowance method is chosen, which fields should be sent to Omniston?

This document is about EVM allowance methods and the corresponding Omniston payload fields. For signature shape rules based on wallet kind, see EVM Signature. For a dedicated explanation of what wallet kind means, see EVM Wallet kind.

Supported allowance methods

Omniston EVM swaps can rely on three different allowance methods:

1. EIP-2612

Official reference: ERC-2612

This is a token-native permit-based allowance method defined by the token contract itself.

• the token exposes a permit(...) function

• allowance can be created from an EIP-712 signature

• no separate approval transaction is needed for that allowance update

2. Permit2

Official reference: Permit2 overview

This is a generalized permit system provided by the Uniswap Permit2 contracts.

• the token is first approved on-chain to the Permit2 contract

• later spender permissions can be granted by Permit2 signed data

• this is useful when the token does not support EIP-2612 but a signature-based allowance method is still desired

Permit2 is usually a hybrid flow:

• one initial gas-paying token approval to Permit2

• then off-chain permit signatures for later orders

3. Native ERC-20 allowance

Official reference: ERC-20

This is the baseline ERC-20 model.

• the wallet sends an on-chain approve(spender, amount) transaction

• the spender later uses transferFrom

• no off-chain permit is attached to the Omniston order payload

This method is the fallback when no signature-based allowance method is available.

Choosing an allowance method

There are really two separate decisions:

Decision A: What does the token support?

• If the token supports EIP-2612, you can use token-native permit.

• If it does not support EIP-2612, you can still use Permit2 if your integration supports the Permit2 setup.

• If neither is available or desired, use native ERC-20 approve.

Decision B: What kind of user flow do you want?

Choose EIP-2612 when:

• the token supports it

• you want the most direct gasless allowance path

• you prefer token-native semantics over an external permit system

Choose Permit2 when:

• the token does not support EIP-2612

• you still want orders to use signatures after initial setup

• you are comfortable requiring a one-time approval to the Permit2 contract

Choose native ERC-20 approve when:

• no signature-based path is available

• the integration wants the simplest universal fallback allowance method

• a normal on-chain approval transaction is acceptable

Allowance methods by wallet kind

Use this matrix as a compatibility shortcut after checking token support. For background on these wallet categories, see EVM Wallet kind.

Wallet kind	EIP-2612	Permit2	Native ERC-20 approve
EOA	yes, gasless	yes, gasless after initial approval	no
Delegated EOA	yes, gasless	no	yes
Contract wallet	no	no	yes

How Omniston interprets allowance data

From Omniston’s point of view there are only two payload modes:

Mode 1: Allowance already in place

Use this when allowance is already available through native ERC-20 approval.

In this case:

• omit encodedPermitData

• omit permitSignature

• omit usePermit2

Mode 2: Signed permit attached

Use this when the order should carry a signed permit.

In this case:

• send encodedPermitData

• send permitSignature

• send usePermit2

Meaning:

• usePermit2 = false means the permit is an EIP-2612 permit

• usePermit2 = true means the permit is a Permit2 allowance permit

Omniston payload examples

These examples focus on the allowance-method part of the integration, including permit-based flows where applicable, while keeping the setup code needed to understand each method end to end.

Example 1: EIP-2612

Not all ERC-20 tokens support EIP-2612, so support needs to be checked for each token individually.

This example uses pUSD on Polygon 0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB.

import { encodeAbiParameters, hexToBytes } from "viem";

const ownerAddress = "0x..."; // trader wallet address on the source EVM chain

const tokenAddress = quote.inputAsset.chain.value.kind.value;
const spenderAddress = quote.settlementData.value.srcProtocolContractAddress.chain.value;

const permitTypedData = {
  domain: {
    name: "Polymarket USD",
    version: "1",
    chainId: 137,
    verifyingContract: "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB",
  },
  types: {
    Permit: [
      { name: "owner", type: "address" },
      { name: "spender", type: "address" },
      { name: "value", type: "uint256" },
      { name: "nonce", type: "uint256" },
      { name: "deadline", type: "uint256" },
    ],
  },
  primaryType: "Permit" as const,
  message: {
    owner: ownerAddress,
    spender: spenderAddress,
    value: BigInt(quote.inputUnits),
    nonce: await getContractNonce(ownerAddress, tokenAddress),
    deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
  },
};

const permitTypedDataSignature = await signTypedData({
  ...permitTypedData,
  account: ownerAddress,
});

declare const permitSignature: Uint8Array;
// Derive `permitSignature` from the wallet signature as described in `evm-signature.md`.

const encodedPermitData = hexToBytes(
  encodeAbiParameters(
    [
      { name: "owner", type: "address" },
      { name: "spender", type: "address" },
      { name: "value", type: "uint256" },
      { name: "nonce", type: "uint256" },
      { name: "deadline", type: "uint256" },
    ],
    [
      permitTypedData.message.owner,
      permitTypedData.message.spender,
      permitTypedData.message.value,
      permitTypedData.message.nonce,
      permitTypedData.message.deadline,
    ],
  ),
);

const evmOrderPayload = await omniston.evmBuildOrderPayload({
  quoteId: quote.quoteId,
  ownerSrcAddress: inputWalletAddress,
  traderDstAddress: outputWalletAddress,
  traderDstDiscloseAddress: outputWalletAddress,
  //
  encodedPermitData,
  permitSignature,
  usePermit2: false,
});

What this means:

• encodedPermitData encodes the signed token-native permit payload

• permitSignature is the corresponding permit signature

• usePermit2: false tells Omniston that this is an EIP-2612 permit

How to derive permitSignature from the wallet signature depends on wallet kind. See EVM Signature.

Example 2: Permit2

This example uses USDC on Base 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

This example uses the Permit2 contract 0x000000000022D473030F116dDEE9F6B43aC78BA3.

Permit2 usually has two parts in the integration flow:

1. one-time ERC-20 approval to the Permit2 contract

2. later off-chain Permit2 signature attached to the Omniston payload

Part 1: Approve the token to Permit2

Before using Permit2 signatures, the token usually needs a one-time ERC-20 approval to the Permit2 contract. That approval is still a regular on-chain transaction, so the wallet needs enough native gas token to submit it.

import { erc20Abi, maxUint256 } from "viem";

const PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";

const ownerAddress = "0x..."; // trader wallet address on the source EVM chain

const tokenAddress = quote.inputAsset.chain.value.kind.value;

const currentAllowance = await readContract(wagmiConfig, {
  address: tokenAddress,
  abi: erc20Abi,
  functionName: "allowance",
  args: [ownerAddress, PERMIT2_ADDRESS],
});

if (currentAllowance < BigInt(quote.inputUnits)) {
  const approveTxHash = await writeContract(walletClient, {
    address: tokenAddress,
    abi: erc20Abi,
    functionName: "approve",
    args: [PERMIT2_ADDRESS, maxUint256],
    account: ownerAddress,
  });

  await waitForTransactionReceipt(wagmiConfig, {
    hash: approveTxHash,
  });
}

After this approval exists, later orders can use Permit2 signed data.

Part 2: Attach the Permit2 allowance permit to the Omniston payload

import { encodeAbiParameters, hexToBytes } from "viem";

const ownerAddress = "0x..."; // trader wallet address on the source EVM chain

const tokenAddress = quote.inputAsset.chain.value.kind.value;
const spenderAddress =
  quote.settlementData.value.srcProtocolContractAddress.chain.value;

const permitTypedData = {
  domain: {
    name: "Permit2",
    chainId: 8453,
    verifyingContract: PERMIT2_ADDRESS,
  },
  types: {
    PermitDetails: [
      { name: "token", type: "address" },
      { name: "amount", type: "uint160" },
      { name: "expiration", type: "uint48" },
      { name: "nonce", type: "uint48" },
    ],
    PermitSingle: [
      { name: "details", type: "PermitDetails" },
      { name: "spender", type: "address" },
      { name: "sigDeadline", type: "uint256" },
    ],
  },
  primaryType: "PermitSingle" as const,
  message: {
    details: {
      token: tokenAddress,
      amount: BigInt(quote.inputUnits),
      expiration: Math.floor(Date.now() / 1000) + 3600,
      nonce: await getPermit2Nonce(ownerAddress, tokenAddress, spenderAddress),
    },
    spender: spenderAddress,
    sigDeadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
  },
};

const permitTypedDataSignature = await signTypedData({
  ...permitTypedData,
  account: ownerAddress,
});

declare const permitSignature: Uint8Array;
// Derive `permitSignature` from the wallet signature as described in `evm-signature.md`.

const encodedPermitData = hexToBytes(
  encodeAbiParameters(
    [
      {
        name: "permitSingle",
        type: "tuple",
        components: [
          {
            name: "details",
            type: "tuple",
            components: [
              { name: "token", type: "address" },
              { name: "amount", type: "uint160" },
              { name: "expiration", type: "uint48" },
              { name: "nonce", type: "uint48" },
            ],
          },
          { name: "spender", type: "address" },
          { name: "sigDeadline", type: "uint256" },
        ],
      },
    ],
    [permitTypedData.message],
  ),
);

const evmOrderPayload = await omniston.evmBuildOrderPayload({
  quoteId: quote.quoteId,
  ownerSrcAddress: inputWalletAddress,
  traderDstAddress: outputWalletAddress,
  traderDstDiscloseAddress: outputWalletAddress,
  //
  encodedPermitData,
  permitSignature,
  usePermit2: true,
});

What this means:

• encodedPermitData encodes the signed Permit2 allowance payload

• permitSignature is the corresponding Permit2 signature

• usePermit2: true tells Omniston that this is a Permit2-based permit

How to derive permitSignature from the wallet signature depends on wallet kind. See EVM Signature.

Example 3: Native ERC-20 approve

Use this when the wallet already granted allowance by a normal on-chain approve.

import { erc20Abi, maxUint256 } from "viem";

const ownerAddress = "0x..."; // trader wallet address on the source EVM chain

const tokenAddress = quote.inputAsset.chain.value.kind.value;
const spenderAddress =
  quote.settlementData.value.srcProtocolContractAddress.chain.value;

const currentAllowance = await readContract(wagmiConfig, {
  address: tokenAddress,
  abi: erc20Abi,
  functionName: "allowance",
  args: [ownerAddress, spenderAddress],
});

if (currentAllowance < BigInt(quote.inputUnits)) {
  const approveTxHash = await writeContract(walletClient, {
    address: tokenAddress,
    abi: erc20Abi,
    functionName: "approve",
    args: [spenderAddress, maxUint256],
    account: ownerAddress,
  });

  await waitForTransactionReceipt(wagmiConfig, {
    hash: approveTxHash,
  });
}

const evmOrderPayload = await omniston.evmBuildOrderPayload({
  quoteId: quote.quoteId,
  ownerSrcAddress: inputWalletAddress,
  traderDstAddress: outputWalletAddress,
  traderDstDiscloseAddress: outputWalletAddress,
});

What this means:

• allowance is expected to already exist on-chain

• Omniston does not receive permit data