Guard signer

client.guardSigner manages backend-managed guard wallets that co-sign protected account actions, such as whitelist updates and whitelist-requirement changes. Every method is authenticated and account-scoped: inputs accept an optional account field ("main", "active", or { subaccountId }).

A guard wallet holds a signer key on the backend. When you perform a protected funding action, you ask the guard signer for an approval signature and submit it alongside the action. See the funding flows for where these approvals are consumed.

Methods

createWallet(input?, options?)

Creates a guard wallet for the resolved account target and returns the generated signer EVM address.

const { signerAddress } = await client.guardSigner.createWallet();
console.log(signerAddress); // "0x..."

getStatus(input?, options?)

Returns stored and live guard signer status: signer address, on-chain signer, initialization state, nonce, and nonce space. Returns null when the backend reports no wallet. nonceSpace is a bigint; do not JSON.stringify the whole object.

const status = await client.guardSigner.getStatus();
if (status) {
	console.log(status.signerAddress, status.initialized, status.nonce);
}

signProtectedAction(input, options?)

Produces one guard approval signature for a supported protected action and returns a GuardApproval, or null when the response has no approval payload. Some actions carry args.

const approval = await client.guardSigner.signProtectedAction({
	action: "fundingAddExternalWhitelist",
	args: {
		case: "externalWhitelist",
		polychainChainId: 1,
		addresses: ["0xabc..."],
	},
});

if (approval) {
	// Submit approval.signature, approval.nonceSpace, approval.deadlineUnix with the action.
	console.log(approval.signature); // "0x..."
}

Supported actions are fundingSetExternalWhitelistRequired, fundingAddExternalWhitelist, fundingRemoveExternalWhitelist, fundingAddInternalWhitelist, fundingRemoveInternalWhitelist, and fundingSetInternalWhitelistRequired. The args union has three cases: externalWhitelist (polychainChainId + addresses), internalWhitelist (addresses), and whitelistRequirement (required). polychainChainId must be an integer from 1 through 4,294,967,295.

batchSignProtectedActions(input, options?)

Produces ordered approvals for a batch of protected actions and returns { approvals }, one per requested action in the same order. It throws if the backend returns a mismatched count.

const { approvals } = await client.guardSigner.batchSignProtectedActions({
	actions: [
		{
			action: "fundingSetExternalWhitelistRequired",
			args: { case: "whitelistRequirement", required: true },
		},
		{
			action: "fundingAddExternalWhitelist",
			args: { case: "externalWhitelist", polychainChainId: 1, addresses: ["0xabc..."] },
		},
	],
});
console.log(approvals.length); // 2, matching the request order

rotateWallet(input?, options?)

Generates a backend-managed replacement guard signer and returns the new signer address plus the rotation approval (or null). Submit the rotation approval to complete the swap on-chain.

const { newSignerAddress, approval } = await client.guardSigner.rotateWallet();
console.log(newSignerAddress);

exportWallet(input?, options?)

Exports the guard signer's private key material and returns { privateKey } as a 0x-prefixed hex string. This is a high-privilege action.

const { privateKey } = await client.guardSigner.exportWallet();
// Store privateKey securely; do not log or transmit it.

The GuardApproval shape

signProtectedAction, batchSignProtectedActions, and rotateWallet return approvals in this shape. nonceSpace and deadlineUnix are stringified big integers; signature is 0x-prefixed hex.

interface GuardApproval {
	nonceSpace: string;
	deadlineUnix: string;
	signature: `0x${string}`;
	raw: { nonceSpace: bigint; deadlineUnix: bigint; signature: Uint8Array<ArrayBuffer> };
}

Related

• Withdrawals for protected funding actions these approvals authorize.
• MFA for the fresh step-up that exportWallet requires.
• Address book for the whitelists these actions modify.
• Errors for the error type reference.

Related Topics