Integration Guide

AsterDex uses a Hybrid Authentication Model to combine the security of self-custody with the speed of centralized trading.

The Flow:

1 User Connects Wallet: Frontend connects to MetaMask/Rabby (EIP-1193).
2 Create "Agent Wallet": Your app generates a random local private key (the "Agent").
3 Authorize Agent: User signs a one-time message with their Main Wallet to whitelist this Agent on the exchange.
4 Trade: The Agent signs all future orders automatically in the background. No more popups!

2. Connecting Wallet (Frontend)

Use standard libraries like ethers.js or wagmi to connect the user's main wallet.

// Generic EIP-1193 Connection
async function connectWallet() {
    if (!window.ethereum) return alert("Install MetaMask!");
    const provider = new ethers.BrowserProvider(window.ethereum);
    await provider.send("eth_requestAccounts", []);
    const signer = await provider.getSigner();
    return signer;
}

3. Authorizing the Agent

This is the critical step. You must generate a local keypair and ask the user to "Login" (authorize it).

const { ethers } = require('ethers');

// 1. Generate Agent (Store this securely in localStorage/Enclave)
const agentWallet = ethers.Wallet.createRandom();
console.log("Agent Address:", agentWallet.address);

// 2. Request Authorization (User Signs with Main Wallet)
async function registerAgent(userSigner, agentAddress) {
    const message = `Login to AsterDex\nAgent: ${agentAddress}\nTimestamp: ${Date.now()}`;
    const signature = await userSigner.signMessage(message);
    
    // Send to API to whitelist this agent for this user
    await axios.post('https://www.asterdex-testnet.com/bapi/auth/register', {
        user: await userSigner.getAddress(),
        agent: agentAddress,
        signature: signature,
        message: message
    });
}

⚠ Important: You only need to do this ONCE per session/device. After registration, the Agent Key can sign orders indefinitely until revoked.

4. Signing & Trading (The "Loop")

Now that you have an authorized Agent Key, you can place orders instantly. Spot orders use EIP-712.

Spot Order Signing (EIP-712)

Use this function to wrap your API calls.

async function placeSpotOrder(agentWallet, orderParams) {
    // Domain Data (Chain ID 714 for AsterDex Testnet)
    const domain = {
        name: "AsterSignTransaction",
        version: "1",
        chainId: 714, 
        verifyingContract: "0x0000000000000000000000000000000000000000"
    };

    const types = { Message: [{ name: "msg", type: "string" }] };

    // Construct the payload (Must be sorted mostly alphabetically)
    // Order: symbol -> side -> type -> quantity -> price -> timeInForce ...
    const nonce = Date.now() * 1000;
    const qs = new URLSearchParams({
        ...orderParams,
        timeInForce: 'GTC',
        nonce: nonce,
        user: agentWallet.address, // Agent acts as user for signature
        signer: agentWallet.address
    }).toString();

    // Sign
    const signature = await agentWallet.signTypedData(domain, types, { msg: qs });

    // Send (Pass signature in body or query)
    return axios.post('https://www.asterdex-testnet.com/api/v3/order', 
        qs + `&signature=${signature}`
    );
}

// Example Usage
placeSpotOrder(agentWallet, {
    symbol: "ASTERUSDT",
    side: "BUY",
    type: "MARKET",
    quoteOrderQty: "10" // Buy 10 USDT worth
});

5. Quick Endpoint Reference

Method	Endpoint	Auth	Description
POST	/api/v3/order	Spot Agent	Place Limit/Market Order
DELETE	/api/v3/order	Spot Agent	Cancel Order
GET	/api/v3/openOrders	Spot Agent	List Active Orders
GET	/api/v3/account	Spot Agent	Get Balances
GET	/api/v3/exchangeInfo	None	Get Symbols & Rules