Partial Fills

Let an order settle for the size that’s actually available - and get the rest back.

Sometimes the right outcome is most of the trade rather than none of it. With partial fills enabled, an order settles for whatever size is actually available at execution - the pattern of choice when firm liquidity is one ingredient in a larger route, or when a shrinking market makes a partial win better than a full miss.

Partial fills are opt-in per intent: set intent.partialFill: true on the quote request. Orders without the flag are all-or-nothing - they settle in full or refund in full.

The Mechanics

Partial-fill behavior is declared, not engineered: the flag rides on your intent, LPs quote knowing partial settlement is acceptable, and the escrow enforces proportionality - whatever fraction of your input is consumed, you receive at least the matching fraction of the quoted output. The unconsumed remainder of your input is released back to you.

There is no calldata surgery on your side. The signed order already encodes the partial-fill terms, and the settlement contract derives the fill arithmetic - your integration just reads the outcome.

What a Partial Outcome Looks Like

A partially filled order reports both sides of the story:

requested input : 1000000000  (1,000 USDC)
consumed input  :  650000000  (650 USDC settled)
delivered output:  649350000  (per the quoted rate, proportionally enforced)
refunded input  :  350000000  (350 USDC released back)

Aspect	Guarantee
Rate	The fill settles at no worse than the quoted rate, pro-rata
Remainder	Unconsumed input is released by the escrow, not left locked
Atomicity per leg	Each settled portion is delivery-versus-payment, same as a full fill

In Practice

1. Quote with the Flag

import httpx

API = "https://api.tetrafi.io/api/v1"
ME = "0x2e7E7cc62919eAf4c502dAC34753cFc5A29e9693"
headers = {"X-API-Key": "tfk_live_..."}

resp = httpx.post(
    f"{API}/rfq/quotes",
    json={
        "user": ME,
        "intent": {
            "intentType": "swap",
            "inputs": [{"user": ME,
                        "asset": {"chainId": 10, "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"},
                        "amount": "1000000000"}],   # 1,000 USDC
            "outputs": [{"receiver": ME,
                         "asset": {"chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],
            "swapType": "ExactInput",
            "partialFill": True,
        },
        "supportedTypes": ["escrow-v0"],
    },
    headers=headers,
)
quotes = resp.json()["quotes"]

Key response behavior:

Field	With partialFill: true
preview.outputs	The full-size delivery if the whole order fills
quote’s fill terms	Carry the pro-rata floor the escrow will enforce on any portion

2. Preflight, Sign, Submit

Nothing changes in your execution code - the partial-fill terms are already inside the payload you sign:

from eth_account import Account
from eth_account.messages import encode_typed_data

selected = quotes[0]

pf = httpx.post(f"{API}/rfq/orders/preflight", headers=headers,
                json={"quoteResponse": selected}).json()

sign_action = next(a for a in pf["nextActions"] if a["purpose"] == "orderSignature")
signable = encode_typed_data(full_message=sign_action["typedData"])
signature = Account.sign_message(signable, private_key="0x<your_private_key>").signature.hex()

order = httpx.post(f"{API}/rfq/orders",
                   headers={**headers, "Idempotency-Key": selected["quoteId"]},
                   json={"quoteResponse": selected, "signature": signature}).json()

3. Read the Settled Amounts

Check the final order record for what actually filled versus what came back:

import time

while True:
    o = httpx.get(f"{API}/rfq/orders/{order['id']}", headers=headers).json()
    if o["status"] in ("settled", "failed"):
        break
    time.sleep(2)

print("status:", o["status"])
# A settled partial fill reports the consumed input, delivered output,
# and refunded remainder on the order record.

End to End

import time

import httpx
from eth_account import Account
from eth_account.messages import encode_typed_data

API = "https://api.tetrafi.io/api/v1"
KEY = "tfk_live_..."
PRIVATE_KEY = "0x<your_private_key_hex>"
ME = "0x2e7E7cc62919eAf4c502dAC34753cFc5A29e9693"

headers = {"X-API-Key": KEY}

# --- 1. Quote 1,000 USDC with partial fills allowed ---
quotes = httpx.post(f"{API}/rfq/quotes", headers=headers, json={
    "user": ME,
    "intent": {
        "intentType": "swap",
        "inputs": [{"user": ME,
                    "asset": {"chainId": 10, "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"},
                    "amount": "1000000000"}],
        "outputs": [{"receiver": ME,
                     "asset": {"chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}],
        "swapType": "ExactInput",
        "partialFill": True,
    },
    "supportedTypes": ["escrow-v0"],
}).json()["quotes"]

selected = quotes[0]
print("Quoted by:", selected["solverId"])

# --- 2. Preflight and sign ---
pf = httpx.post(f"{API}/rfq/orders/preflight", headers=headers,
                json={"quoteResponse": selected}).json()
sign_action = next(a for a in pf["nextActions"] if a["purpose"] == "orderSignature")
signable = encode_typed_data(full_message=sign_action["typedData"])
signature = Account.sign_message(signable, private_key=PRIVATE_KEY).signature.hex()

# --- 3. Submit ---
order = httpx.post(f"{API}/rfq/orders",
                   headers={**headers, "Idempotency-Key": selected["quoteId"]},
                   json={"quoteResponse": selected, "signature": signature}).json()

# --- 4. See how much filled ---
while True:
    o = httpx.get(f"{API}/rfq/orders/{order['id']}", headers=headers).json()
    if o["status"] in ("settled", "failed"):
        print("final:", o["status"])
        break
    time.sleep(2)