Skip to main content
Reads and subscriptions for one account use that account’s user address, not its API-wallet address. userRole is the exception: pass the address whose role you want to look up, including an API wallet. Each action’s endpoint page explains how to sign it. Isolated Operation Status is a signed read and requires authorization for the requested account.

​
Before Trading

A deployment can require protocol access before trading. Query POST /info with {"type":"checkAccess","user":"0x..."} and require isAuthorized: true. Terms state is available through {"type":"checkTerms","user":"0x..."}; require hasAccepted: true for the current terms version. If either check fails, the account owner must complete onboarding before the client trades.

​
Who Can Sign

Notional verifies which address signed the request and which user’s account it may change:
  • A direct user signature acts for that same address.
  • An approved API wallet can act for its approving user only where the endpoint allows API wallets.
  • Reads and subscriptions continue to use the user’s address, not the API-wallet address.
Approving an API wallet delegates eligible actions; it does not create a second trading account. See Approve API Wallet for the approval request and API Wallets for the resulting authorization state.

​
Action Types

Each action page shows the exact JSON fields and any action-specific signing or expiration rules:

​
Signing Domains

A signing domain is the name and chain information included in an EIP-712 signature. Notional trading actions use the NotionalExchange domain. A signature created for a venue’s domain cannot be used as a Notional signature, or vice versa. Agent approval and withdrawals use NotionalSignTransaction with their own primary types. Polymarket deposit reports use NotionalPolymarketDeposit. Follow the action’s signing section; these formats are not interchangeable.

​
Exchange Action Signing

Orders, cancels, modifies, TWAPs, leverage updates, isolated-margin updates, outcome operations, and protocol transfers use signNotionalOrder from @notional/common. The helper constructs the canonical action hash and signs an EIP-712 Agent message in the NotionalExchange domain, version 1, chain ID 1337, with the zero address as verifyingContract. source is "a" for mainnet and "b" for testnet. For example, sign an order with an already approved API wallet:
Send request as JSON to POST /exchange. Only include expiresAfter for actions that support it, and pass the same value to the signing helper and request. Version 2 outcome operations omit it; protocol transfers require it. Leave the vault-address argument undefined. Although these actions share a signing format, their signer permissions differ: protocol transfers require the account owner’s signature. The helper’s name does not mean that only orders use it, nor does the EIP-712 type Agent authorize an API wallet for every action.

​
Nonces

A nonce is a Unix-millisecond number that prevents the same signed request from being used twice. For actions that include a nonce:
  • Use a Unix-millisecond integer within [now - 2 days, now + 1 day].
  • Nonces are tracked per signer, including an API wallet acting for its approving user.
  • Notional remembers up to 20 recent nonces per signer. Once full, a new nonce must be greater than the smallest remembered nonce and must never have been used.
  • Use one shared counter across every process that uses the same signer. Date.now() alone can produce duplicates when requests are created at the same time.
  • expiresAfter, where supported, sets an expiry time; it does not replace the nonce.
Nonce reuse normally fails. Some actions can return the saved response for an exact retry of the same signed action; cancel requests intentionally reject duplicate nonces. Follow the action page and check the current result before retrying.

​
Signing Rules

  • Format the action exactly as its endpoint page requires, sign it, and do not change it afterward.
  • Use the action’s documented signing domain, chain, JSON fields, and signer restrictions.
  • A signature can recover the expected wallet locally and still fail if the server verifies different fields or a different signing domain.
Failure shapes and retry guidance are centralized in Error Responses.