Get Quote

Endpoint Information

Endpoint: GET /api/v1/router/quote

Description: Get an EIP-712-signed quote that can be executed on-chain by calling StoveRouter.execute().

Authentication: Institution API Key + Signature (non-Maker API endpoint — X-Maker-Addr is not required). See Authorization

Request Parameters

Parameter	Type	Required	Description
ticker	string	Yes	Ticker symbol. Use AAPL for StockToken, AAPLs for ShareToken (with s suffix)
exchange	int	Yes	Exchange code — shared Exchange enum, see Precise Execution API Overview (0 = U.S. Stock Exchange, 1 = Hong Kong Stock Exchange, 3 = South Korea Stock Exchange)
is_buy	bool	Yes	true for buy, false for sell
chain_id	int	Yes	Blockchain network ID
asset	string	Yes	Payment token contract address (USDT/USDC) — must be the default asset for the chain
amount_in	string	Yes	Input amount in natural units (human-readable). For buys: asset token amount (e.g., 1000 for 1000 USDT). For sells: share quantity (e.g., 10 for 10 shares)
amount_type	string	No	Amount type, applies to buys only. stablecoin (default) or stocktoken

amount_type values

Value	Description	Use case
stablecoin	amount_in is a stablecoin amount (default)	Buying with a fixed USDT/USDC spend
stocktoken	amount_in is a share quantity	Buying a fixed number of shares

Token Decimals

The router supports two token types with different decimal precision:

Token Type	Ticker Format	Decimals	Description
StockToken	AAPL, TSLA	0 (integer)	Each token = 1 share, no fractional amounts
ShareToken	AAPLs, TSLAs (with s suffix)	18 (wei)	ERC-20 with 18 decimal precision for fractional shares

Important:

• Request parameter amount_in: Uses natural units (human-readable), e.g., 1000 for 1000 USDT, 10 for 10 shares
• Response field amount_in: Follows token decimal precision:
  • ShareToken amounts: 18 decimals (multiply by 1e18), e.g., 10000000000000000000 = 10 ShareTokens
  • StockToken amounts: 0 decimals (integers only), e.g., 10 = 10 StockTokens
  • Asset token amounts: Follows asset token's decimals (e.g., USDT on BSC = 18 decimals)

Response Parameters

Field	Type	Description
quote	object	Quote data (passed to StoveRouter.execute())
signature	string	EIP-712 signature
required_approvals	array	ERC-20 approvals required before execution

quote object

Field	Type	Description
quote_id	string	Unique quote identifier (bytes32)
ticker	string	Ticker symbol (AAPL for StockToken, AAPLs for ShareToken)
exchange	int	Exchange code
is_buy	bool	Whether this is a buy
chain_id	int	Blockchain network ID
amount_type	string	stablecoin_in or stocktoken_in
amount_in	string	Original input amount in token decimal precision. For buys: asset token amount. For sells: ShareToken/StockToken quantity (see Token Decimals)
amount_in_used	string	Amount actually used. Decimal precision depends on token type
amount_out	string	Output amount. For buys: ShareToken/StockToken quantity (token-specific decimals). For sells: asset token amount (follows asset token decimals)
fee_amount	string	Fee amount (follows asset token decimals)
stock_token	string	StockToken or ShareToken contract address
asset_token	string	Payment token contract address (USDT/USDC/etc.)
price	string	Price per share (follows asset token decimals)
expires_at	int	Quote expiry (Unix timestamp, seconds)

required_approvals[]

Field	Type	Description
token_address	string	Token contract address requiring approval
spender	string	Approval target address (StoveRouter contract)
amount	string	Approval amount (follows the asset token's native decimals)
description	string	Human-readable approval description

Request Examples

Buy ShareToken with a fixed stablecoin amount (1000 USDT for AAPLs, BSC testnet):

curl -X GET "{API_BASE_URL}/api/v1/router/quote?ticker=AAPLs&exchange=0&is_buy=true&chain_id=97&asset=0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91&amount_in=1000"

Buy StockToken with a fixed stablecoin amount (1000 USDT for AAPL):

curl -X GET "{API_BASE_URL}/api/v1/router/quote?ticker=AAPL&exchange=0&is_buy=true&chain_id=97&asset=0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91&amount_in=1000"

Buy a fixed ShareToken quantity (10 ShareTokens of AAPLs):

curl -X GET "{API_BASE_URL}/api/v1/router/quote?ticker=AAPLs&exchange=0&is_buy=true&chain_id=97&asset=0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91&amount_in=10&amount_type=stocktoken"

Buy a fixed StockToken quantity (10 shares of AAPL):

curl -X GET "{API_BASE_URL}/api/v1/router/quote?ticker=AAPL&exchange=0&is_buy=true&chain_id=97&asset=0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91&amount_in=10&amount_type=stocktoken"

Sell ShareToken (6 ShareTokens of AAPLs):

curl -X GET "{API_BASE_URL}/api/v1/router/quote?ticker=AAPLs&exchange=0&is_buy=false&chain_id=97&asset=0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91&amount_in=6"

Sell StockToken (6 shares of AAPL):

curl -X GET "{API_BASE_URL}/api/v1/router/quote?ticker=AAPL&exchange=0&is_buy=false&chain_id=97&asset=0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91&amount_in=6"

Response Example

ShareToken Quote Response

{
    "code": 0,
    "data": {
        "quote": {
            "quote_id": "0xabc123def456789012345678901234567890123456789012345678901234",
            "ticker": "AAPLs",
            "exchange": 0,
            "is_buy": true,
            "chain_id": 97,
            "amount_type": "stablecoin_in",
            "amount_in": "1000000000000000000000",
            "amount_in_used": "999000000000000000000",
            "amount_out": "6000000000000000000",
            "fee_amount": "2992507492507492507",
            "stock_token": "0x1c6611cde556f439252c2845c33702c3035fe351",
            "asset_token": "0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91",
            "price": "166500000000000000000",
            "expires_at": 1735660860
        },
        "signature": "0x1234567890abcdef...",
        "required_approvals": [
            {
                "token_address": "0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91",
                "spender": "0xD1fCC25B80Ec3d7f00ab948c1fFF0Ba75994ac0e",
                "amount": "999000000000000000000",
                "description": "Approve USDT to StoveRouter for buying"
            }
        ]
    }
}

Note: Response amounts use token decimal precision:

• amount_in: 1000000000000000000000 = 1000 USDT (18 decimals, BSC USDT)
• amount_out: 6000000000000000000 = 6 ShareTokens (18 decimals)

StockToken Quote Response

{
    "code": 0,
    "data": {
        "quote": {
            "quote_id": "0xdef456abc123456789012345678901234567890123456789012345678901",
            "ticker": "AAPL",
            "exchange": 0,
            "is_buy": true,
            "chain_id": 97,
            "amount_type": "stablecoin_in",
            "amount_in": "1000000000000000000000",
            "amount_in_used": "999000000000000000000",
            "amount_out": "6",
            "fee_amount": "2992507492507492507",
            "stock_token": "0x2d7711cde556f439252c2845c33702c3035fe352",
            "asset_token": "0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91",
            "price": "166500000000000000000",
            "expires_at": 1735660860
        },
        "signature": "0xabcdef1234567890...",
        "required_approvals": [
            {
                "token_address": "0x09671802Cc9Bbf6402f2e7a07b220Aa7b43D8c91",
                "spender": "0xD1fCC25B80Ec3d7f00ab948c1fFF0Ba75994ac0e",
                "amount": "999000000000000000000",
                "description": "Approve USDT to StoveRouter for buying"
            }
        ]
    }
}

Note: Response amounts use token decimal precision:

• amount_in: 1000000000000000000000 = 1000 USDT (18 decimals, BSC USDT)
• amount_out: 6 = 6 StockTokens (0 decimals, integer representation)

Notes

• Quote validity: quotes expire after 10 seconds — request a new quote if it expires.
• Asset whitelist: asset must be the default asset address for the given chain (USDT, USDC, etc.).
• Token types:
  • StockToken (AAPL): 0 decimals, whole shares only
  • ShareToken (AAPLs): 18 decimals, supports fractional amounts
• Decimal precision:
  • Request amount_in: Natural units (human-readable), e.g., 1000 for 1000 USDT, 10 for 10 shares
  • Response amounts: Follow token's decimal precision:
    • ShareToken: 18 decimals (multiply by 1e18)
    • StockToken: 0 decimals (integers only)
    • Asset token: Follows the asset token's native decimals (varies by chain and token)
• Next: see Execute Transaction for how to build and submit the on-chain transaction.