Token Approvals

Grant the allowances that let settlement pull your input tokens - once, or per trade.

Settlement can only pull the tokens you have allowed it to, through the ordinary ERC-20 allowance: approve() on the token, granting a named spender the right to move up to a chosen amount. The RFQ and Router APIs share one escrow, so the flow is identical.

Finding the Right Spender

Run preflight on your selected quote; nextActions include any approval step with the exact spender and amount.

Approval addresses are not constants. They shift with chain and lock type; preflight is the only authority. Some tokens need none: USDC-style tokens settle via EIP-3009 transferWithAuthorization, authorized inside your signature.

Reading Current Allowance

If the existing allowance already covers the trade, an extra approval is wasted gas.

from web3 import Web3

ERC20_ABI = [
    {
        "constant": True,
        "inputs": [
            {"name": "_owner", "type": "address"},
            {"name": "_spender", "type": "address"},
        ],
        "name": "allowance",
        "outputs": [{"name": "", "type": "uint256"}],
        "type": "function",
    },
    {
        "constant": False,
        "inputs": [
            {"name": "_spender", "type": "address"},
            {"name": "_value", "type": "uint256"},
        ],
        "name": "approve",
        "outputs": [{"name": "", "type": "bool"}],
        "type": "function",
    },
]

w3 = Web3(Web3.HTTPProvider("https://mainnet.optimism.io"))

def check_allowance(owner: str, token_address: str, spender: str) -> int:
    token = w3.eth.contract(
        address=Web3.to_checksum_address(token_address),
        abi=ERC20_ABI,
    )
    return token.functions.allowance(
        Web3.to_checksum_address(owner),
        Web3.to_checksum_address(spender),
    ).call()

Granting Allowance

Two strategies: a maximum grant (2^256 - 1) per token, once, which solvers and aggregators default to; or a per-trade grant of exactly what each trade needs, tighter but paying approval gas every time.

from eth_account import Account

PRIVATE_KEY = "0x<your_private_key>"

def ensure_allowance(account, token_address: str, spender: str, required: int):
    current = check_allowance(account.address, token_address, spender)
    if current >= required:
        return  # already approved

    token = w3.eth.contract(
        address=Web3.to_checksum_address(token_address),
        abi=ERC20_ABI,
    )

    tx = token.functions.approve(
        Web3.to_checksum_address(spender),
        2**256 - 1,  # max approval
    ).build_transaction({
        "from": account.address,
        "nonce": w3.eth.get_transaction_count(account.address),
        "gasPrice": w3.eth.gas_price,
    })

    signed = w3.eth.account.sign_transaction(tx, private_key=PRIVATE_KEY)
    tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
    w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120)

Wiring It into the Trade Flow

Run preflight and execute any approval action before signing. Approval actions are ready-to-broadcast transactions, type: "evmTransaction" with purpose: "tokenApproval" and the calldata in tx:

import httpx

preflight = httpx.post(
    "https://api.tetrafi.io/api/v1/router/orders/preflight",
    json={"quoteResponse": selected_quote},
    headers={"X-API-Key": YOUR_API_KEY},
).json()

for action in preflight["nextActions"]:
    if action["purpose"] == "tokenApproval" and action["actor"] == "userWallet":
        tx = action["tx"]  # {to, data, value} - broadcast as returned
        signed = w3.eth.account.sign_transaction(
            {**tx, "from": account.address,
             "nonce": w3.eth.get_transaction_count(account.address),
             "gasPrice": w3.eth.gas_price},
            private_key=PRIVATE_KEY,
        )
        w3.eth.wait_for_transaction_receipt(
            w3.eth.send_raw_transaction(signed.raw_transaction), timeout=120
        )
# Actions with frequency "reusableSetup" persist across trades.

Funding Locks Beyond approve()

Preflight selects the lock for your corridor and token: Permit2 (one approval of the Permit2 contract per token, then each pull is authorized by an EIP-712 signature), EIP-3009, or a resource lock. It is not a per-request choice. Details under Settlement & Smart Contracts.