> For the complete documentation index, see [llms.txt](https://docs.hypersurface.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hypersurface.io/integration-guide.md).

# Integration Guide

Integrate the current HyperEVM USDC PremiumPool deployment

This guide targets the **HyperEVM USDC PremiumPool** used by [the application](https://app.hypersurface.io). Use the [current contract registry](https://docs.hypersurface.io/contracts/hyper-evm.md) for addresses and verification evidence. The previous HyperEVM USD₮0 HedgedPool examples are preserved in the [legacy integration guide](https://docs.hypersurface.io/legacy-integration-guide.md); their addresses and order ABI are not interchangeable with this deployment.

## Network and services

| Setting                  | Value                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| Network                  | HyperEVM mainnet                                                                                  |
| Chain ID                 | `999`                                                                                             |
| Native gas token         | HYPE                                                                                              |
| Public RPC               | `https://rpc.hyperliquid.xyz/evm`                                                                 |
| Explorer                 | `https://hyperevmscan.io`                                                                         |
| Quote API                | `https://market-api-sh-usdc.hypersurface.io`                                                      |
| Premium and strike token | USDC; address and decimals in the [registry](https://docs.hypersurface.io/contracts/hyper-evm.md) |

Services are configured in the application configuration and deployment manifest.

Read-only quote-service availability check:

```sh
curl --fail 'https://market-api-sh-usdc.hypersurface.io/underlyingPrices?symbol=HYPE'
```

This endpoint returned HTTP 200 during the registry review. `/health` returned HTTP 404; do not use the old guide's `/health` request as a current health check. A price response does not establish that a signed order can execute.

## Resolve the deployment

Use the PremiumPool proxy as the entry point. It exposes `addressBook()`, `premiumToken()`, `strikeToken()`, `oracle()` and `blackScholes()`. Resolve Controller, MarginPool and TradeExecutor through the AddressBook's `getController()`, `getMarginPool()` and `getTradeExecutor()`.

Compare the public getters and AddressBook values with the registry at a consistent block. The pool's cached Controller, MarginPool and TradeExecutor fields are internal; there are no public getters for those cached fields. AddressBook reads alone do not prove their cache freshness. Simulate the intended operation before submission. The [registry](https://docs.hypersurface.io/contracts/hyper-evm.md#read-only-verification) includes read-only commands. Do not substitute a legacy component when a read fails.

Get eligible underlyings from `PremiumPool.getAllUnderlyings()`. Collateral can differ from the underlying for a supported staked-asset product. Read token `decimals()` and use the supported underlying/collateral pairing from the current application and quote service; historical token tables do not establish current support.

## Request and preserve a signed quote

`POST /quote` uses the structure below. The function arguments are caller-supplied values for the selected market. `signedAmount` is a signed integer string in option units, not a floating-point token amount. Select a currently offered series symbol rather than a hard-coded expiry from an old example.

```javascript
const PREMIUM_POOL = "0x6806c2c11d9aa3464792d10455a6480d793eedc1";
const QUOTE_API = "https://market-api-sh-usdc.hypersurface.io";

async function requestQuote({ account, underlying, collateral, referrer, symbol, signedAmount }) {
  const response = await fetch(`${QUOTE_API}/quote`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      sign: true,
      order: {
        account,
        poolAddress: PREMIUM_POOL,
        underlying,
        collateral,
        referrer,
        legs: [{ symbol, amount: signedAmount }],
      },
    }),
  });
  const body = await response.json();
  if (!response.ok || !body.result?.order) throw new Error("Quote request failed");
  return body.result.order;
}
```

This follows the current application quote client (source snapshots are recorded in the [registry](https://docs.hypersurface.io/contracts/hyper-evm.md#maintainer-source-snapshots)). Preserve `result.order`, including every signed field. Validate its account, pool, underlying, collateral, side, size, expiry, premium, fee and validity deadline against the user's intent. Use integer strings, BigInt or a big-number library throughout; do not convert token amounts to `Number`.

## Current order ABI

This interface matches IOrderUtil.sol and PremiumPool.sol. Field order is part of the ABI.

```solidity
interface IPremiumPoolIntegration {
    struct Signature {
        uint8 v;
        bytes32 r;
        bytes32 s;
    }

    struct OptionLeg {
        uint256 strike;
        uint256 expiration;
        bool isPut;
        int256 amount;
        int256 premium;
        uint256 fee;
        uint256 iv;
    }

    struct Order {
        address account;
        address poolAddress;
        address underlying;
        address collateral;
        address referrer;
        uint256 validUntil;
        uint256 nonce;
        uint256 underlyingPrice;
        OptionLeg[] legs;
        Signature signature;
        Signature[] coSignatures;
    }

    function trade(Order calldata order, uint256 traderVaultId, bool autoCreateVault)
        external returns (address);

    function withdrawVaultCollateral(uint256 vaultId, address collateralAsset, uint256 withdrawalAmount)
        external;
}
```

`underlyingPrice` uses `1e8` precision. `iv` uses `1e18` fixed-point precision. Both are signed quote fields required by this contract version. An older generated SDK that omits either field encodes a different function selector. Generate bindings from the current interface instead of copying the legacy ABI.

## Approvals and trading

Calculate required collateral using the current vault state and the MarginCalculator resolved through `AddressBook.getMarginCalculator()`, following the TradeExecutor behavior below. Use the registry's current spender addresses and finite allowances for the amount required by the selected operation.

| Operation                  | Token approved       | Spender       | Trade arguments                                                               |
| -------------------------- | -------------------- | ------------- | ----------------------------------------------------------------------------- |
| Open a covered call        | Selected collateral  | TradeExecutor | Negative leg amount; new vault: `traderVaultId = 0`, `autoCreateVault = true` |
| Open a cash-secured put    | Strike token (USDC)  | TradeExecutor | Negative leg amount; new vault: `traderVaultId = 0`, `autoCreateVault = true` |
| Buy back an existing short | Premium token (USDC) | PremiumPool   | Positive leg amount; existing vault ID; `autoCreateVault = false`             |

For a put requiring additional collateral, the executor pulls the margin shortfall minus gross premium plus fee from the trader; the pool contributes gross premium minus fee. For a covered call, the executor pulls the required collateral and the pool pays gross premium minus fee. For buyback, PremiumPool pulls premium plus fee. Account for existing vault collateral when calculating a shortfall. Do not approve MarginPool merely because it ultimately holds collateral.

Simulate the exact call from the intended account and estimate gas before submission. Refresh an expired or invalid quote rather than modifying signed values. The current pool processes a single option leg. A positive amount is the buyback path for an existing short vault, not a standalone long-opening trade.

`trade()` returns an **oToken address**, not a vault ID. A receipt does not directly expose a Solidity return value. When opening a vault, obtain its ID from the TradeExecutor's `MarginVaultOpened(address indexed trader, uint256 vaultId)` event and persist it with the chain, owner, pool and series. Never assume a global vault number.

## Closing, collateral withdrawal and expiry

For early closure, request a fresh buyback quote for the same series and submit it with the existing vault ID. After the short is burned, collateral withdrawal is a separate operation through `withdrawVaultCollateral(uint256,address,uint256)`; Controller collateral constraints still apply.

For expiry settlement, the current application submits a `SettleVault` action to `Controller.operate`, with the trader as owner and recipient. The action uses the existing `vaultId`, the trader address for both `owner` and `secondAddress`, and zero for `asset`, `amount` and `index`. The Controller ABI is `operate((uint8 actionType,address owner,address secondAddress,address asset,uint256 vaultId,uint256 amount,uint256 index,bytes data)[] actions)`; `SettleVault` is action type `7`. The current application uses the zero address encoded as bytes for `data`. Read `canSettleExpiry(expiry)` and the exercise-window views before offering settlement. Expiry alone does not guarantee immediate settlement or an automatic wallet payout.

The application window checks use `exerciseWindow()`, `exerciseWindowAfterExpiration()` and `canExercise(oToken)`. Treat RPC errors separately from a valid `false` result.

## Indexing and historical positions

The application manifest selects this subgraph:

```
https://api.goldsky.com/api/public/project_clysuc3c7f21y01ub6hd66nmp/subgraphs/hypersurface-hyperevm-subgraph/latest/gn
```

Use on-chain state for final transaction decisions. Indexer configuration does not guarantee freshness. Preserve deployment identity: a legacy USD₮0 vault is not a USDC vault, and its allowance or settlement target cannot be migrated by replacing an address in a code sample.

See [historical HyperEVM addresses](https://docs.hypersurface.io/contracts/hyper-evm.md#legacy-addresses) and the [legacy integration guide](https://docs.hypersurface.io/legacy-integration-guide.md). The legacy auction and rebate references have not been certified as compatible with the current PremiumPool deployment.
