Place HIP-4 orders, cancel, and convert outcome tokens

The Trading Adapter (adapter.trading) lets you submit and cancel orders on HIP-4 prediction market outcomes. Before you can place any orders you must authenticate using adapter.auth.initAuth() - the trading adapter returns an error result (rather than throwing) if you attempt to place an order without a valid signer. Order placement performs local validation for tick alignment, notional size, and minimum shares before signing, so most errors are caught before hitting the exchange.

You must call adapter.auth.initAuth(walletAddress, signer) before using any trading methods. See the Auth Adapter page for the full authentication flow, including agent key setup.

`placeOrder(params)`

Places a single order on a HIP-4 outcome. This method never throws - check the success field and the error message on the returned result instead. For limit orders, the SDK performs these local checks before signing:

Tick-aligns the price to 5 significant figures.
Validates that the notional value (price × amount) meets the minimum (10 USDC) unless skipMinNotionalCheck is true.
When markPx is provided, validates that amount meets the minimum shares threshold.

For market orders, the SDK fetches the current mid and applies 8% slippage (ceiling for buys, floor for sells), then clamps the result to [0.0001, 0.9999].

const result = await adapter.trading.placeOrder({
  marketId: "516",
  outcome: "#5160",
  side: "buy",
  type: "limit",
  price: "0.65",
  amount: "100",
});

if (!result.success) {
  console.error(result.error);
}

Parameters

string

required

The outcome ID as a string (e.g. "516").

string

required

The side identifier. Use the coin string (e.g. "#5160" for side 0, "#5161" for side 1). This determines which side of the outcome you are trading.

string

required

"buy" or "sell".

string

required

"market" or "limit".

string

Limit price as a decimal string (0–1). Required for limit orders. Ignored for market orders (the SDK computes price from the mid with slippage).

string

required

Order size in shares.

string

default:"GTC"

Time-in-force for limit orders. One of "GTC", "GTD", "FOK", "FAK". See the TIF mapping table below. Ignored for market orders.

number

Current market price (0–1). When provided, the SDK enforces a minimum shares check: amount >= getMinShares(markPx), which ensures the order meets the 10 USDC minimum notional.

string

Optional referral address that receives builder fees. Checksummed addresses are accepted; the SDK lowercases the value before signing.

number

Builder fee in tenths of a basis point. 0 = no fee. 100 = 0.1%. Maximum is 1000 (1.0%).

boolean

When true, skips the SDK’s local minimum-notional and minimum-shares pre-checks. Use this for position-closing flows where the residual size may be below 10 USDC but the exchange still accepts the order.

TIF mapping

The SDK maps SDK-level TIF values to Hyperliquid order types as follows:

SDK `timeInForce`	Order `type`	Hyperliquid TIF	Notes
`"GTC"` (default)	`"limit"`	`Gtc`	Good-till-cancelled
`"GTD"`	`"limit"`	`Gtc`	No true GTD support; behaves as GTC
`"FOK"`	`"limit"`	`Ioc`	True FOK semantics not enforced
`"FAK"`	`"limit"`	`Ioc`	Immediate-or-cancel
(any)	`"market"`	`FrontendMarket`	Slippage-protected best-execution

Return type

Promise<PredictionOrderResult> - never throws.

boolean

required

true if the order was accepted by the exchange.

string

Hyperliquid order ID. Present when the order filled or is resting.

string

"filled" - fully executed. "resting" - sitting in the book. "error" - exchange rejected the order. "unknown" - unrecognized response.

string

Filled size. Only present when status === "filled".

string

Error message. Present when success === false.

Examples

import { createHIP4Adapter } from "@outcome.xyz/hip4";
import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
import {
  getAgentApprovalTypedData,
  submitAgentApproval,
} from "@outcome.xyz/hip4";

const adapter = createHIP4Adapter({ testnet: false });
await adapter.initialize();

// --- Authentication (agent key flow) ---
const agentKey = generatePrivateKey();
const agent = privateKeyToAccount(agentKey);
const typedData = getAgentApprovalTypedData(
  agent.address,
  "My App",
  Date.now(),
  false,
);
const sig = await walletClient.signTypedData(typedData);
await submitAgentApproval(sig, agent.address, "My App", Date.now(), false);
await adapter.auth.initAuth(userAddress, agent);

// --- Place a limit buy order ---
const limitResult = await adapter.trading.placeOrder({
  marketId: "516",
  outcome: "#5160", // side 0 (e.g. "Yes")
  side: "buy",
  type: "limit",
  price: "0.65",
  amount: "100",
  timeInForce: "GTC",
  markPx: 0.65, // enables minimum-shares validation
});

if (limitResult.success) {
  console.log("Order status:", limitResult.status);
  // "filled" or "resting"
  if (limitResult.status === "filled") {
    console.log("Filled shares:", limitResult.shares);
  }
} else {
  console.error("Order failed:", limitResult.error);
}

// --- Place a market sell order ---
const marketResult = await adapter.trading.placeOrder({
  marketId: "516",
  outcome: "#5161", // side 1 (e.g. "No")
  side: "sell",
  type: "market",
  amount: "50",
});

// --- Limit buy with builder fee ---
const builderResult = await adapter.trading.placeOrder({
  marketId: "516",
  outcome: "#5160",
  side: "buy",
  type: "limit",
  price: "0.70",
  amount: "25",
  builderAddress: "0xYourBuilderAddress",
  builderFee: 100, // 0.1%
});

// --- Close a small residual position, skipping notional check ---
const closeResult = await adapter.trading.placeOrder({
  marketId: "516",
  outcome: "#5160",
  side: "sell",
  type: "limit",
  price: "0.60",
  amount: "3",
  skipMinNotionalCheck: true,
});

`cancelOrder(params[])`

Cancels one or more resting orders. Unlike placeOrder, this method throws on failure.

await adapter.trading.cancelOrder([
  { marketId: "516", orderId: "12345", outcome: "#5160" },
]);

Parameters

cancelOrder accepts an array of cancel requests:

string

required

The outcome ID as a string.

string

required

The Hyperliquid order ID to cancel. Obtain this from placeOrder’s orderId field or from adapter.account.fetchOpenOrders().

string

Optional side identifier (e.g. "#5160"). Providing this resolves the correct side asset ID. When omitted, the SDK defaults to side 0.

Return type

Promise<void> - resolves when all cancels are confirmed. Throws if authentication is missing or the exchange rejects the request.

The current implementation always resolves the cancel asset ID to side 0 unless you provide the outcome field. If you placed an order on side 1 ("#5161"), you must pass outcome: "#5161" to cancel it correctly.

Example

// Cancel a single resting order
await adapter.trading.cancelOrder([
  { marketId: "516", orderId: "12345", outcome: "#5160" },
]);

// Cancel multiple orders at once
await adapter.trading.cancelOrder([
  { marketId: "516", orderId: "12345", outcome: "#5160" },
  { marketId: "516", orderId: "67890", outcome: "#5161" },
]);

// Fetch open orders first, then cancel them
const openOrders = await adapter.account.fetchOpenOrders(userAddress);
const cancels = openOrders.map((order) => ({
  marketId: String(order.outcomeId),
  orderId: String(order.oid),
  outcome: order.coin,
}));
await adapter.trading.cancelOrder(cancels);

Token conversions

Four protocol-level share-conversion primitives that move value between USDC and outcome tokens without touching the orderbook. They settle directly against your spot balances at the bundle-equivalence mint price - no spread paid, no slippage, no liquidity required. See the Converting tokens concept for the math, and the Token conversions guide for end-to-end code. All four methods use the same userOutcome action envelope, sign via L1 agent signing, and return a WalletActionResult. None of them throw.

type WalletActionResult = {
  success: boolean;
  error?: string;
  filledSz?: string;
  avgPx?: string;
  oid?: number;
};

Conversions affect your spot balances immediately on success: true. The SDK does not preview or simulate. Validate inputs before calling.

`splitOutcome(params)`

Burn X USDC and mint X Yes shares + X No shares of one outcome.

await adapter.trading.splitOutcome({
  outcome: 5160,
  amount: "100",
});

Parameters

number

required

Numeric outcome ID. Matches market.outcomeId on a fetched HIP-4 market.

string

required

USDC amount to split, as a decimal string (e.g. "12.5"). The SDK strips trailing zeros to match Hyperliquid’s wire format. X USDC burned → X Yes + X No minted.

Return type

Promise<WalletActionResult> - never throws.

`mergeOutcome(params)`

The inverse of splitOutcome. Burn X Yes + X No of one outcome and mint X USDC.

await adapter.trading.mergeOutcome({
  outcome: 5160,
  amount: "100",
});

// Or burn the max available:
await adapter.trading.mergeOutcome({ outcome: 5160, amount: null });

Parameters

number

required

Numeric outcome ID.

string | null

required

Paired-share count to merge, as a decimal string. Pass null to merge the maximum available - the protocol burns min(yes_balance, no_balance) shares.

Return type

Promise<WalletActionResult> - never throws.

`mergeQuestion(params)`

Burn X Yes shares from every outcome of a question (including the fallback) and mint X USDC. Lets you redeem a full Yes-bundle for collateral before the question resolves.

await adapter.trading.mergeQuestion({
  question: 42,
  amount: "10",
});

// Or redeem the max available:
await adapter.trading.mergeQuestion({ question: 42, amount: null });

Parameters

number

required

Numeric question ID. For multi-outcome and price-bucket markets, this is market.questionId. Default-binary markets have no parent question - use mergeOutcome instead.

string | null

required

Yes-share count to redeem from each member outcome, as a decimal string. Pass null to redeem the maximum - min(yes_balance) across every outcome of the question.

Return type

Promise<WalletActionResult> - never throws.

`negateOutcome(params)`

Burn X No shares of one outcome and mint X Yes shares of every other outcome in the same question (including the fallback). Converts “I don’t think this wins” into “I think one of the others wins” without touching the orderbook.

await adapter.trading.negateOutcome({
  question: 42,
  outcome: 5160,
  amount: "5",
});

Parameters

number

required

Numeric question ID containing the source outcome.

number

required

Source outcome ID whose No shares are being converted. Must belong to question.

string

required

No-share count to convert, as a decimal string. After the call, your No balance on outcome drops by amount, and you hold amount additional Yes shares of every other outcome under question.

Return type

Promise<WalletActionResult> - never throws.

The on-wire sub-action key is negateOutcome, matching Hyperliquid’s testnet “Convert Outcomes” UI. Hyperliquid’s docs body shows negateQuestion in places - that’s a typo in their docs. The SDK sends negateOutcome.

Get Started

Concepts

Adapters

Utilities

Rewards

Changelog

Place HIP-4 orders, cancel, and convert outcome tokens

`placeOrder(params)`

Parameters

TIF mapping

Return type

Examples

`cancelOrder(params[])`

Parameters

Return type

Example

Token conversions

`splitOutcome(params)`

Parameters

Return type

`mergeOutcome(params)`

Parameters

Return type

`mergeQuestion(params)`

Parameters

Return type

`negateOutcome(params)`

Parameters

Return type

​placeOrder(params)

​Parameters

​TIF mapping

​Return type

​Examples

​cancelOrder(params[])

​Parameters

​Return type

​Example

​Token conversions

​splitOutcome(params)

​Parameters

​Return type

​mergeOutcome(params)

​Parameters

​Return type

​mergeQuestion(params)

​Parameters

​Return type

​negateOutcome(params)

​Parameters

​Return type

`placeOrder(params)`

Parameters

TIF mapping

Return type

Examples

`cancelOrder(params[])`

Parameters

Return type

Example

Token conversions

`splitOutcome(params)`

Parameters

Return type

`mergeOutcome(params)`

Parameters

Return type

`mergeQuestion(params)`

Parameters

Return type

`negateOutcome(params)`

Parameters

Return type