Instant Swap API Overview

What It Does

Aggregators (e.g. wallet swap widgets, DEX aggregators) get an EIP-712-signed quote for a stock-token trade, then execute it on-chain in a single atomic transaction by calling the StoveRouter contract directly — no backend order lifecycle, no locking step.

Who It's For

DEX aggregators and wallets that build and broadcast their own transactions, and want to compose stock-token swaps alongside other on-chain operations.

Access

Getting a quote require Institution API Key + Signature authentication. Executing a trade on mainnet requires your calling contract address to be on an on-chain caller whitelist — otherwise StoveRouter.execute() reverts with UnauthorizedCaller. Testnet does not require whitelisting — any caller can execute against the testnet StoveRouter.

To get whitelisted for mainnet, contact business@stove.finance with:

• Your integration (aggregator) name
• Your calling contract address
• Supported chain IDs
• A technical contact

Once approved, Stove adds your calling contract address to the whitelist.

Integration Flow

1. Get a quote — GET /api/v1/router/quote
2. Check allowance — confirm the user has approved the required token to StoveRouter
3. Submit approval (if needed)
4. Build the transaction — construct the StoveRouter.execute() call
5. Broadcast — user signs and broadcasts the transaction

Contract Addresses

Testnet Chain

Contract	Address
StoveRouter	0xD1fCC25B80Ec3d7f00ab948c1fFF0Ba75994ac0e
USDT	0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91
USDC	0x4F891B3d31425FD9993789f0Ce0577C3e953d099

Mainnet Chain

Contract	Address
StoveRouter	0x3ad52C80582A5af5A2A36D570Bcb2D751329b699
USDT	0x55d398326f99059fF775485246999027B3197955
USDC	0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d

Pages in This Section

Page	Purpose
Get Quote	GET /api/v1/router/quote — get an EIP-712-signed quote
Execute Transaction	Build and execute the on-chain transaction (not a REST endpoint)
Market Data Push (WebSocket)	Push of chain-denominated prices (router_quote, router_price)

Notes

• Quotes use EIP-712 signatures, verifiable on-chain.
• Settlement is atomic — a single transaction, no locking step.
• Each quoteId can only be used once (replay protection).
• Whitelist enforcement applies to mainnet only — testnet does not require caller whitelisting.
• Time format: timestamps use ISO 8601 or Unix time.