Authorization API

Endpoints for building and submitting delegate authorizations

Endpoints for building and submitting delegate authorizations (agent wallets, builder fees, etc.).

These endpoints are intended to be used via @lifi/perps-sdk. The typed data signing and submission flow is complex and best handled by the SDK.

---

POST /createAuthorization

Build authorization payloads for the user to sign.

POST /v1/perps/createAuthorization

Flow

1. Call GET /dexes to discover available authorizations and their parameters
2. Call this endpoint with the desired authorizations array
3. Backend checks the current state and returns only unsatisfied authorizations
4. Sign the typedData in each returned action with the user’s wallet
5. Submit all signatures to POST /authorization

Request Body

{
  "dex": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "authorizations": [
    {
      "key": "ApproveAgent",
      "params": {
        "agentAddress": "0x5678901234abcdef5678901234abcdef56789012"
      }
    },
    {
      "key": "ApproveBuilderFee",
      "params": {}
    }
  ]
}

Field	Type	Required	Description
dex	string	Yes	DEX identifier
address	string	Yes	User’s wallet address (account owner)
signerAddress	string	No	Address that will sign the payloads. Required for USER_AGENT mode (set to agent address). Defaults to address.
authorizations	AuthorizationInput[]	Yes	Authorizations to build

Each AuthorizationInput:

Field	Type	Required	Description
key	string	Yes	Authorization key from dex.authorizations[].key
params	object	No	Authorization-specific parameters

Response 201

{
  "actions": [
    {
      "action": "ApproveAgent",
      "description": "Approve agent wallet for trading on your behalf",
      "typedData": {
        "domain": {
          "name": "HyperliquidSignTransaction",
          "version": "1",
          "chainId": 42161,
          "verifyingContract": "0x0000000000000000000000000000000000000000"
        },
        "types": {
          "EIP712Domain": [
            { "name": "name", "type": "string" },
            { "name": "version", "type": "string" },
            { "name": "chainId", "type": "uint256" },
            { "name": "verifyingContract", "type": "address" }
          ],
          "HyperliquidTransaction:ApproveAgent": [
            { "name": "hyperliquidChain", "type": "string" },
            { "name": "agentAddress", "type": "address" },
            { "name": "agentName", "type": "string" },
            { "name": "nonce", "type": "uint64" }
          ]
        },
        "primaryType": "HyperliquidTransaction:ApproveAgent",
        "message": {
          "hyperliquidChain": "Mainnet",
          "agentAddress": "0x5678901234abcdef5678901234abcdef56789012",
          "agentName": "LI.FI Agent",
          "nonce": 1234567890
        }
      }
    }
  ]
}

If an authorization is already active, it will not appear in the actions array. An empty actions array means all requested authorizations are already satisfied.

SDK: createAuthorization(), perps.buildAuthorization()

---

POST /authorization

Submit signed authorizations.

POST /v1/perps/authorization

Request Body

{
  "dex": "hyperliquid",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "actions": [
    {
      "action": "ApproveAgent",
      "typedData": { "...original typedData from createAuthorization..." },
      "signature": "0xabcd1234..."
    },
    {
      "action": "ApproveBuilderFee",
      "typedData": { "...original typedData from createAuthorization..." },
      "signature": "0xefgh5678..."
    }
  ]
}

Field	Type	Required	Description
dex	string	Yes	DEX identifier
address	string	Yes	User’s wallet address (account owner)
signerAddress	string	No	Address that signed the payloads. Required for USER_AGENT mode. Defaults to address.
actions	SignedAuthorization[]	Yes	Signed authorization payloads

Each SignedAuthorization:

Field	Type	Required	Description
action	string	Yes	Authorization action type
typedData	object	Yes	Original typedData from /createAuthorization
signature	string	Yes	User’s signature of the typedData

Response 202

{
  "results": [
    { "action": "ApproveAgent", "success": true },
    { "action": "ApproveBuilderFee", "success": true }
  ]
}

Each AuthorizationResult:

Field	Type	Description
action	string	Authorization action type
success	boolean	Whether the authorization was accepted
error	string	Error message (if failed)

This endpoint returns 202 Accepted. On-chain processing is asynchronous and typically completes within the next block. Poll GET /account to verify authorizations are active.

Response 400

Validation error (invalid parameters or malformed request).

SDK: submitAuthorization(), perps.submitAuthorizations()