What is an Authorized Wallet

An authorized wallet is an account that has been whitelisted by another to delegate trading permissions on its behalf, allowing users to divide responsibilities and manage deposited funds more securely.

Because of the nature of DeFi, each wallet has its own funds and positions on chain. An Authorized Wallet only has permission to sign trade actions (posting and cancelling orders, adjusting margin/leverage and managing positions) on behalf of the Parent Wallet that authorized it, but not to Withdraw from, or deposit to, the Parent’s account.

How do Authorized Wallets Work

Any wallet address (Parent Wallet) may whitelist another wallet address (Authorized Wallet) to be able to trade on its behalf. This gives the authorized wallet permission to sign certain contract interactions on behalf of the Parent Wallet using their own private key; the parent never needs to share their private key. These permissions are limited to trading interactions and exclude the ability to deposit or withdraw funds from the Parent’s Account.

For every API call, you may add a parent wallet address that you wish the action to be performed on. If your wallet address has been authorized by the parent, your API request will be approved and actioned (excluding withdraw and deposit requests).

Authorization Process

Authorized Wallets are only available for API-based trading:

Authorizing a wallet

When a user wants to authorize a wallet to act on their account’s behalf, they will send a /api/v1/trade/accounts/authorize PUT request to the Gateway, with the wallet that they want to authorized in the authorizedAccountAddress field in the signedFields part of the request.

For code examples in Python and Rust please refer to this section.

Deauthorizing a wallet

When a user wants to deauthorize a wallet to stop acting on their account’s behalf, they will send a /api/v1/trade/accounts/deauthorize PUT request to the Gateway, with the wallet that they want to deauthorize in the authorizedAccountAddress field in the signedFields part of the request.

For code examples in Python and Rust please refer to this section.

Authentication as an authorized wallet

When a user who has an authorized wallet to act on behalf of an account wants to get an auth token, the user will call the /auth/v2/token endpoint in the Auth Service. The signer of the request should be the authorized wallet. The account address of the request should be the address that authorized the wallet to act on it’s behalf. The Auth Service will check the signature, and retrieve the signer address from it. It will then make a call to the Matching Engine to check if the user’s wallet is actually authorized for this account. If it is, then the Auth Service will issue an auth token where the sub field is the account address (the address that the wallet will act on behalf of) and the authorizedUserAddress field is the signer of the request (the wallet address that will sign the requests on behalf of the account).

NOTE: If the account is getting an auth token, then the authorizedUserAddress is the signer of the request, meaning the wallet getting the authorization.