> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tide.ag/llms.txt
> Use this file to discover all available pages before exploring further.

# Register API Key

> Register API keys with exchanges to enable trading operations. Links server wallet to exchange accounts.

Register API keys with exchanges to enable trading operations. This endpoint links your server wallet to exchange accounts and generates the necessary credentials.

<Warning>
  **Important**: You must create a server wallet first using `POST /api/wallets` before registering API keys.
</Warning>

## Features

* **Multi-exchange support**: Generate API keys for Aster and Hyperliquid
* **Wallet-based registration**: Link API keys to server wallets
* **Secure storage**: API credentials are encrypted and stored securely
* **Automatic signing**: Server handles message signing for authentication

## Supported Exchanges

| Exchange    | Endpoint                               | Notes                          |
| ----------- | -------------------------------------- | ------------------------------ |
| Aster       | `POST /api/trading/aster/apikey`       | Generates API key and secret   |
| Hyperliquid | `POST /api/trading/hyperliquid/apikey` | Creates API wallet with expiry |
| Lighter     | N/A                                    | Use Lighter platform directly  |

<Note>
  **Lighter DEX**: You do NOT register API keys through HyperDEX for Lighter. Instead, create an account on [Lighter DEX](https://app.lighter.xyz), deposit funds, and generate API keys from their platform. Provide these credentials as query parameters when placing orders.
</Note>

***

## Aster API Key Registration

Register your server wallet with Aster exchange to get API credentials.

### Endpoint

`POST /api/trading/aster/apikey`

### Request Body

```json theme={null}
{
  "walletIdOrAddress": "user_123"
}
```

### Request Parameters

| Field               | Type   | Required | Description                                               |
| ------------------- | ------ | -------- | --------------------------------------------------------- |
| `walletIdOrAddress` | string | Yes      | Can be userId, walletId (UUID), or wallet address (0x...) |

### Example Request

```bash theme={null}
curl -X POST https://api.tide.ag/api/trading/aster/apikey \
  -H "Content-Type: application/json" \
  -d '{"walletIdOrAddress": "user_123"}'
```

```javascript theme={null}
await axios.post('https://api.tide.ag/api/trading/aster/apikey', {
  walletIdOrAddress: 'user_123'
});
```

### What Happens

1. Server retrieves the wallet using the provided identifier
2. Server signs a message using the wallet's MPC key shares
3. Aster verifies the signature to authenticate the wallet
4. Aster returns API key and secret
5. API credentials are encrypted and stored in the database

### Success Response

```json theme={null}
{
  "success": true,
  "message": "API key generated successfully",
  "data": {
    "signerAddress": "0x173404aAAa4d6539e2C7dbcC1931Cf41b3A3D5c7",
    "createdAt": "2025-11-27T02:00:00Z"
  },
  "timestamp": 1762765034479
}
```

### Response Fields

| Field                | Type    | Description                          |
| -------------------- | ------- | ------------------------------------ |
| `success`            | boolean | Operation status                     |
| `message`            | string  | Success message                      |
| `data.signerAddress` | string  | Wallet address registered with Aster |
| `data.createdAt`     | string  | ISO timestamp of registration        |
| `timestamp`          | number  | Unix timestamp in milliseconds       |

***

## Hyperliquid API Key Registration

Register your server wallet with Hyperliquid exchange to create an API wallet.

### Endpoint

`POST /api/trading/hyperliquid/apikey`

### Request Body

```json theme={null}
{
  "walletIdOrAddress": "user_123"
}
```

### Request Parameters

| Field               | Type   | Required | Description                                               |
| ------------------- | ------ | -------- | --------------------------------------------------------- |
| `walletIdOrAddress` | string | Yes      | Can be userId, walletId (UUID), or wallet address (0x...) |

### Example Request

```bash theme={null}
curl -X POST https://api.tide.ag/api/trading/hyperliquid/apikey \
  -H "Content-Type: application/json" \
  -d '{"walletIdOrAddress": "user_123"}'
```

```javascript theme={null}
await axios.post('https://api.tide.ag/api/trading/hyperliquid/apikey', {
  walletIdOrAddress: 'user_123'
});
```

### What Happens

1. Server creates a new API wallet for Hyperliquid
2. Server signs an agent approval message
3. Hyperliquid verifies and approves the API wallet
4. API wallet credentials are encrypted and stored

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    "apiWalletAddress": "0x1A31d05B2B58d559D578E13E0Fb77cB197D36A08",
    "apiPrivateKey": "0x0e6b33d1867274a297f977f0d82f186b0fb053ad80fbc60969decd9908140a0a",
    "mainWalletAddress": "0x90EA34C09B612AC68E696BdC7be0ED037a086E72",
    "expiryTimestamp": 1780240026028
  },
  "timestamp": 1764688027666
}
```

### Response Fields

| Field                    | Type    | Description                                   |
| ------------------------ | ------- | --------------------------------------------- |
| `success`                | boolean | Operation status                              |
| `data.apiWalletAddress`  | string  | Generated API wallet address                  |
| `data.apiPrivateKey`     | string  | API wallet private key (encrypted in storage) |
| `data.mainWalletAddress` | string  | Main server wallet address                    |
| `data.expiryTimestamp`   | number  | API key expiration timestamp (Unix ms)        |
| `timestamp`              | number  | Unix timestamp in milliseconds                |

***

## Lighter API Key Registration

<Warning>
  **Lighter DEX Requirement**: You do NOT register API keys through HyperDEX for Lighter DEX.
</Warning>

### How to Get Lighter API Keys

1. **Create Account**: Visit [Lighter DEX](https://app.lighter.xyz) and create an account
2. **Deposit Funds**: Deposit USDC directly on the Lighter platform
3. **Generate API Keys**: Navigate to your account settings and generate API keys
4. **Note Credentials**: Save your:
   * `apiKeyPrivateKey` - Your API key private key (hex format)
   * `apiKeyIndex` - API key index number
   * `accountIndex` - Your Lighter account index

### Using Lighter API Keys

When placing orders on Lighter through HyperDEX, provide these credentials as query parameters:

```bash theme={null}
POST /api/trading/lighter/orders?apiKeyPrivateKey=<key>&apiKeyIndex=<index>&accountIndex=<account>
```

See the [Place Order documentation](/trading/open-position) for more details.

***

## Error Responses

### 400 Bad Request - Missing Parameters

```json theme={null}
{
  "success": false,
  "error": "Missing required parameter: walletIdOrAddress",
  "timestamp": 1762765034479
}
```

### 404 Not Found - Wallet Not Found

```json theme={null}
{
  "success": false,
  "error": "Wallet not found",
  "timestamp": 1762765034479
}
```

### 409 Conflict - Key Already Exists

```json theme={null}
{
  "success": false,
  "error": "API key already exists for this wallet",
  "message": "Use the existing key or delete it before creating a new one",
  "timestamp": 1762765034479
}
```

### 500 Internal Server Error

```json theme={null}
{
  "success": false,
  "error": "Failed to generate API key",
  "timestamp": 1762765034479
}
```

***

## Use Cases

* Initial account setup for trading on Aster and Hyperliquid
* Link server wallets to exchange accounts
* Enable automated trading through API credentials
* Secure multi-exchange trading setup

***

## Important Notes

<Warning>
  **Security**: API credentials are encrypted and stored securely in the database. Never expose API keys or private keys to clients.
</Warning>

<Note>
  **Prerequisites**: You must create a server wallet using `POST /api/wallets` before registering API keys.
</Note>

<Tip>
  **Wallet Identifiers**: You can use any of these identifiers for `walletIdOrAddress`:

  * `userId` (e.g., "user\_123")
  * `walletId` (UUID format)
  * `address` (0x... format)
</Tip>

<Info>
  **Lighter Integration**: For Lighter DEX, create your account and generate API keys directly on their platform. Then provide those credentials as query parameters when placing orders through HyperDEX.
</Info>


## OpenAPI

````yaml POST /api/trading/{exchange}/apikey
openapi: 3.1.0
info:
  title: Tide API
  description: >-
    Decentralized Perpetual Aggregator API for multi-exchange trading across
    Hyperliquid, Aster, Lighter, and Pacifica
  version: 1.0.0
  contact:
    name: Tide Support
    email: support@tide.ag
    url: https://tide.ag
  license:
    name: MIT
servers:
  - url: https://api.tide.ag
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Market Data
    description: Public market data endpoints
  - name: Trading
    description: Order placement and management
  - name: Positions
    description: Position management and history
  - name: Account
    description: Account and balance management
  - name: System
    description: System status and health
paths:
  /api/trading/{exchange}/apikey:
    post:
      tags:
        - Account
      summary: Register API Key
      description: >-
        Register API keys with exchanges to enable trading operations. Links
        server wallet to exchange accounts.
      parameters:
        - name: exchange
          in: path
          required: true
          schema:
            type: string
            enum:
              - hyperliquid
              - aster
          description: >-
            Exchange adapter name (aster or hyperliquid). Note: Lighter requires
            direct platform registration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterAPIRequest'
            examples:
              aster:
                summary: Aster registration
                value:
                  walletIdOrAddress: user_123
              hyperliquid:
                summary: Hyperliquid registration
                value:
                  walletIdOrAddress: user_123
      responses:
        '200':
          description: API key generated successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AsterRegisterAPIResponse'
                  - $ref: '#/components/schemas/HyperliquidRegisterAPIResponse'
        '400':
          description: Bad request - missing required parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'Missing required parameter: walletIdOrAddress'
                  timestamp:
                    type: integer
        '404':
          description: Wallet not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Wallet not found
                  timestamp:
                    type: integer
        '409':
          description: Conflict - API key already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: API key already exists for this wallet
                  message:
                    type: string
                    example: >-
                      Use the existing key or delete it before creating a new
                      one
                  timestamp:
                    type: integer
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Failed to generate API key
                  timestamp:
                    type: integer
      security: []
components:
  schemas:
    RegisterAPIRequest:
      type: object
      properties:
        walletIdOrAddress:
          type: string
          description: Can be userId, walletId (UUID), or wallet address (0x...)
      required:
        - walletIdOrAddress
    AsterRegisterAPIResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          example: API key generated successfully
        data:
          type: object
          properties:
            signerAddress:
              type: string
              description: Wallet address registered with Aster
            createdAt:
              type: string
              format: date-time
              description: ISO timestamp of registration
        timestamp:
          type: integer
    HyperliquidRegisterAPIResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            apiWalletAddress:
              type: string
              description: Generated API wallet address
            apiPrivateKey:
              type: string
              description: API wallet private key (encrypted in storage)
            mainWalletAddress:
              type: string
              description: Main server wallet address
            expiryTimestamp:
              type: integer
              description: API key expiration timestamp
        timestamp:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        API key for authentication. Also requires X-API-SECRET, X-API-TIMESTAMP,
        and X-API-SIGNATURE headers for private endpoints.

````