Input Units

The SDK accepts human-readable values for prices, order sizes, and transfer amounts. It validates and converts these values into protocol units before sending a request.

Blockchain integers are serialized as decimal strings in JSON.

Value types

Value	SDK input	Rules
price	Human decimal string	Up to 1 decimal place
size	Human decimal string	Up to 2 decimal places
amount	Human decimal string	Up to 2 decimal places
nonce	bigint or decimal string	Unsigned 64-bit integer
assetId	bigint or decimal string	Canonical unsigned integer
epoch	bigint or decimal string	Canonical unsigned integer
Balance values	Decimal string	Returned in protocol units
Address	EVM hexadecimal string	Valid 20-byte address
Order ID or hash	Hexadecimal string	Valid bytes32 value

Human decimal strings

Order and transfer inputs should be passed as strings rather than JavaScript numbers.

await exchange.placeOrder({
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
  side: false,
  price: "99.9",
  size: "10.25",
});

Use:

price: "99.9"
size: "10.25"
amount: "100.50"

Do not use:

price: 99.9
size: 10.25
amount: 100.5

Strings avoid floating-point rounding and allow the SDK to validate decimal precision exactly.

Price conversion

Prices support one decimal place and are interpreted in cents before being converted into protocol units.

For example:

"99.9" → 999000n

Applications should pass the human-readable price to the SDK. Do not perform this conversion manually when using ExchangeClient.

Size and amount conversion

Sizes and transfer amounts support up to two decimal places.

Examples of valid inputs:

"10"
"10.2"
"10.25"

Inputs with more than two decimal places are rejected:

"10.255"

Zero amounts, invalid precision, negative values, and out-of-range values are rejected before the SDK sends a request.

ProtocolBigNumberish

Protocol integer fields accept ProtocolBigNumberish, which is:

• A bigint

• A canonical unsigned decimal string

Examples:

const assetId = 1n;
const epoch = "12";
const nonce = 113377280000000000n;

Avoid JavaScript numbers for protocol integers:

const assetId = 1; // Do not use for protocol integer inputs

JavaScript numbers cannot safely represent every protocol value.

Addresses

Addresses must use standard EVM hexadecimal format:

0x1111111111111111111111111111111111111111

The SDK provides string utilities for:

• Address validation

• Non-zero address validation

• Hexadecimal-data validation

• bytes32 validation

• Case-insensitive address comparison

import {
  parseAddress,
} from "@gammaswap/v2-exchange-sdk/string-inputs";

const account = parseAddress(
  "0x1111111111111111111111111111111111111111",
);

Relevant address fields are normalized before signed action hashes and signatures are validated.

Integer utilities

Integer-input helpers are available from:

import {
  parseUnsignedInteger,
} from "@gammaswap/v2-exchange-sdk/integer-inputs";

These helpers accept canonical decimal strings and bigint values.

They intentionally reject JavaScript numbers unless a specific helper explicitly supports safe JSON or runtime integers.

Direct API requests

The SDK accepts human decimal inputs and performs the required conversion.

Direct HTTP request bodies use converted protocol values represented as decimal strings.

For example, an SDK call may use:

{
  price: "99.9",
  size: "10.25"
}

The signed HTTP action contains the converted integer values:

{
  "price": "999000",
  "size": "1025"
}

When constructing direct HTTP requests, conversion must happen before hashing and signing. Changing a value after signing invalidates the signature.