Swap integration

Check execution availability

Connect a user-controlled wallet and require HyperEVM chain 999. Recheck the account and chain immediately before each approval or swap request. A quote response has not undergone complete sender-specific execution simulation.

Build the reviewed transaction

// quote is the fresh response from POST /api/v1/quote.
// walletAddress is the connected account on HyperEVM 999.
const response = await fetch('/api/v1/swap', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    quoteId: quote.quoteId,
    sender: walletAddress,
    recipient: walletAddress,
    amountOutMinimum: quote.minimumReceived,
    deadline: Math.floor(Date.now() / 1000) + 300
  })
});
const prepared = await response.json();
if (!response.ok) throw new Error(prepared.error?.message ?? 'Build failed');

This same-origin example assumes the app proxies /api/v1 to Path. A server integration can call https://api.pathagg.xyz. The API keeps quoteId in server memory; expiry or a service restart may require a new quote. deadline is a Unix timestamp in seconds and must be within the next 20 minutes.

The builder validates the executor runtime code and bindings, quote minimum, sender balance, block context and freshness. The returned transaction contains chainId, to, data and value. It is unsigned; the API never submits a user swap.

Approval and preflight

1. Inspect approval. If required, verify its token, spender and exact amount against the reviewed input and configured executor.
2. Ask the wallet to approve that exact ERC20 amount and wait for its receipt. Native HYPE uses transaction.value instead.
3. Get a fresh quote after approval and rebuild. Preserve the previously reviewed minimum and recipient; ask for a new review if they change. Recheck the approval spender.
4. Require simulation.status = simulated for the newly built transaction. approval-required is not a successful full simulation.
5. Decode and verify chain, target, input, recipient, minimum, deadline and value. Estimate gas from the actual wallet; reserve HYPE for gas.
6. Request the wallet signature and broadcast only after those checks.

A user rejecting the swap does not revoke an approval already mined. Never treat a quote expiry as permission to silently lower the reviewed minimum.

Track the transaction hash

curl "https://api.pathagg.xyz/api/v1/transactions/YOUR_TRANSACTION_HASH"

A chain reorganization can invalidate a receipt. Retry the same hash after CHAIN_REORGANIZED. Path activity, when configured, indexes only successful swaps through the configured PathExecutor, not every transaction in a wallet.