Account Action Types: Leverage, Agents, and Funding

Account actions govern everything outside the order book: how much leverage an account uses, which delegate wallets may trade on its behalf, and how USDC moves between the exchange and Solana. Some of these actions are fully user-controlled; others — particularly those that touch on-chain bridge events — are restricted to authorized relayer signers. Type signatures are drawn directly from src/types.ts. Each section below indicates whether the action is user-signed or relayer-only.

SetUserMarketLeverage

User-signed. owner must equal the envelope signer’s derived address.

Pick a per-market initial-margin override for the account. The engine takes max(market.imBps, userImBps) on every IM check, so users can only deleverage relative to the market floor — they cannot exceed the market’s own IM requirement. Setting userImBps to 0 clears any existing override and reverts to the market default.

export interface SetUserMarketLeverage {
  owner: Address;
  market: number;
  userImBps: number;
}

owner

Address

required

20-byte account address picking the override. Must equal the envelope signer’s derived address.

market

number

required

Market identifier the override applies to.

userImBps

number

required

Initial margin override in basis points. 0 clears the override and reverts to the market default. Any non-zero value must be >= market.imBps; the engine rejects lower values with UserLeverageBelowMarketIm (error code 38).

// Set a 20% initial margin requirement on market 1 (5x max leverage)
await client.submitTx({
  type: "SetUserMarketLeverage",
  data: {
    owner: address,
    market: 1,
    userImBps: 2000, // 20%
  },
});

// Clear the override — revert to market default
await client.submitTx({
  type: "SetUserMarketLeverage",
  data: {
    owner: address,
    market: 1,
    userImBps: 0,
  },
});

ApproveAgent

User-signed. Signed by the delegating account owner.

Approve a delegate Ed25519 keypair (an “agent wallet”) to place and cancel orders on the owner’s behalf. The approved agent can submit all order-management actions but cannot withdraw funds or move collateral. Delegation is identified by the full 32-byte Ed25519 public key.

export interface ApproveAgent {
  owner: Address;
  agentPubkey: Uint8Array; // 32 bytes
}

owner

Address

required

20-byte account address granting the delegation.

agentPubkey

Uint8Array

required

Ed25519 public key of the agent wallet (32 bytes). The engine derives a 20-byte address from this key and records it as the authorized agent.

import { generateKeypair, pubkeyToOwner } from "@proof/trading-sdk";

const agent = generateKeypair();

await client.submitTx({
  type: "ApproveAgent",
  data: {
    owner: address,
    agentPubkey: agent.publicKey, // 32-byte Uint8Array
  },
});

RevokeAgent

User-signed. Signed by the delegating account owner.

Revoke a previously approved agent wallet. After revocation the agent’s signatures are rejected by the engine immediately. Identify the agent by its 32-byte Ed25519 public key.

export interface RevokeAgent {
  owner: Address;
  agentPubkey: Uint8Array; // 32 bytes
}

owner

Address

required

20-byte account address revoking the delegation.

agentPubkey

Uint8Array

required

Ed25519 public key of the agent wallet to revoke (32 bytes). Must match the key passed to the corresponding ApproveAgent action.

await client.submitTx({
  type: "RevokeAgent",
  data: {
    owner: address,
    agentPubkey: agent.publicKey,
  },
});

WithdrawRequest

User-signed. Initiates the two-step withdrawal flow.

Request a USDC withdrawal to a Solana address. The requested amount is debited from the account balance immediately and placed into a Pending withdrawal record. The relayer then picks up the record, executes the Solana transfer, and calls either ConfirmWithdrawal or FailWithdrawal.

export interface WithdrawRequest {
  owner: Address;
  amount: bigint;
  solanaDestination: Uint8Array; // 32 bytes
}

owner

Address

required

20-byte account address requesting the withdrawal.

amount

bigint

required

Withdrawal amount in microUSDC (6 decimal places). For example, 100_000_000n = $100.00 USDC.

solanaDestination

Uint8Array

required

Solana destination public key (Ed25519, 32 bytes). This is the raw public key bytes — not a base58 address string.

await client.submitTx({
  type: "WithdrawRequest",
  data: {
    owner: address,
    amount: 500_000_000n,          // $500.00 USDC
    solanaDestination: solanaPublicKeyBytes, // 32-byte Uint8Array
  },
});

WithdrawalRecord and WithdrawalStatus

These types are returned by queryWithdrawal and mirror the engine’s WithdrawalRecord struct field-for-field.

export type WithdrawalStatus = "Pending" | "Completed" | "Failed";

export interface WithdrawalRecord {
  id: bigint;
  owner: Address;
  amount: bigint;
  solanaDestination: Uint8Array;
  status: WithdrawalStatus;
  requestHeight: bigint;
}

Field	Type	Description
`id`	`bigint`	Engine-assigned withdrawal ID used in `ConfirmWithdrawal` and `FailWithdrawal`
`owner`	`Address`	20-byte address that requested the withdrawal
`amount`	`bigint`	Requested amount in microUSDC
`solanaDestination`	`Uint8Array`	32-byte Solana destination public key
`status`	`WithdrawalStatus`	`"Pending"` → `"Completed"` or `"Pending"` → `"Failed"`; never reverses
`requestHeight`	`bigint`	Block height at which the `WithdrawRequest` was admitted

ConfirmDeposit

Relayer-only. The envelope signer’s derived address must equal signer and be on the relayer allowlist.

Confirm an on-chain USDC deposit that was observed on Solana. The solanaTxSig field acts as an idempotency key — re-submitting the same signature is a no-op. This is the preferred production deposit path; use Deposit only for dev/bootstrap scenarios.

export interface ConfirmDeposit {
  owner: Address;
  amount: bigint;
  solanaTxSig: Uint8Array;
  signer: Address;
}

owner

Address

required

20-byte account address to credit.

amount

bigint

required

Deposit amount in microUSDC (6 decimal places).

solanaTxSig

Uint8Array

required

Solana transaction signature (typically 64 bytes) used for idempotency. Duplicate signatures are ignored.

signer

Address

required

Authorized relayer signer address (20 bytes). Must match the envelope signer’s derived address and be on the relayer allowlist.

ConfirmWithdrawal

Relayer-only. The envelope signer must match signer and be on the relayer allowlist.

Mark a Pending withdrawal as Completed after the USDC transfer was sent on Solana. This transitions WithdrawalRecord.status to "Completed" and records the Solana transaction signature.

export interface ConfirmWithdrawal {
  withdrawalId: bigint;
  solanaTxSig: Uint8Array;
  signer: Address;
}

withdrawalId

bigint

required

Engine-assigned withdrawal ID (from WithdrawalRecord.id).

solanaTxSig

Uint8Array

required

Solana transaction signature for the completed transfer (typically 64 bytes).

signer

Address

required

Authorized relayer signer address (20 bytes).

FailWithdrawal

Relayer-only. The envelope signer must match signer and be on the relayer allowlist.

Mark a Pending withdrawal as permanently Failed and refund the debited balance back to the account. This transitions WithdrawalRecord.status to "Failed".

export interface FailWithdrawal {
  withdrawalId: bigint;
  reason: string;
  signer: Address;
}

withdrawalId

bigint

required

Engine-assigned withdrawal ID (from WithdrawalRecord.id).

reason

string

required

Human-readable reason for the failure. Stored in the withdrawal record and surfaced to clients.

signer

Address

required

Authorized relayer signer address (20 bytes).

Deposit

Relayer-only. Legacy credit action — prefer ConfirmDeposit for production flows tied to Solana bridge events.

Directly credit USDC to an account without a corresponding Solana transaction. Per audit B1 (2026-04-23) the envelope signer’s derived address must equal signer, and signer must be on the on-chain relayer allowlist. Clients outside the allowlist receive UnauthorizedRelayer.

export interface Deposit {
  owner: Address;
  amount: bigint;
  signer: Address;
}

owner

Address

required

20-byte account address to credit.

amount

bigint

required

Deposit amount in microUSDC (6 decimal places). For example, 100_000_000n = $100.00 USDC.

signer

Address

required

Authorized relayer signer address (20 bytes). Must match the envelope signer’s derived address and be on the relayer allowlist.

Withdraw

Relayer-only. Prefer WithdrawRequest + ConfirmWithdrawal for the standard two-step user withdrawal flow.

Directly debit USDC from an account, checking margin requirements. Per audit B2 (2026-04-23) the same relayer-authorization contract applies as Deposit.

export interface Withdraw {
  owner: Address;
  amount: bigint;
  signer: Address;
}

owner

Address

required

20-byte account address to debit.

amount

bigint

required

Withdrawal amount in microUSDC (6 decimal places).

signer

Address

required

Authorized relayer signer address (20 bytes). Must match the envelope signer’s derived address and be on the relayer allowlist.

Authorization Summary

Action	Signer Requirement
`SetUserMarketLeverage`	Owner (user-signed; `owner` == envelope signer)
`ApproveAgent`	Owner
`RevokeAgent`	Owner
`WithdrawRequest`	Owner
`ConfirmDeposit`	Relayer allowlist
`ConfirmWithdrawal`	Relayer allowlist
`FailWithdrawal`	Relayer allowlist
`Deposit`	Relayer allowlist
`Withdraw`	Relayer allowlist

Client

Actions

Query Responses

Crypto & Codec

Account Action Types: Leverage, Agents, and Funding

SetUserMarketLeverage

ApproveAgent

RevokeAgent

WithdrawRequest

WithdrawalRecord and WithdrawalStatus

ConfirmDeposit

ConfirmWithdrawal

FailWithdrawal

Deposit

Withdraw

Authorization Summary

Build docs developers (and LLMs) love

Client

Actions

Query Responses

Crypto & Codec

Documentation Index

​SetUserMarketLeverage

​ApproveAgent

​RevokeAgent

​WithdrawRequest

​WithdrawalRecord and WithdrawalStatus

​ConfirmDeposit

​ConfirmWithdrawal

​FailWithdrawal

​Deposit

​Withdraw

​Authorization Summary

Build docs developers (and LLMs) love

SetUserMarketLeverage

ApproveAgent

RevokeAgent

WithdrawRequest

WithdrawalRecord and WithdrawalStatus

ConfirmDeposit

ConfirmWithdrawal

FailWithdrawal

Deposit

Withdraw

Authorization Summary