> ## 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.

# Create Server Wallet

> Create a new MPC-secured server wallet for a user

# Server Wallet Management

Create and manage server-side wallets secured with MPC (Multi-Party Computation) key management through Dynamic Labs. These wallets are used for all trading operations across supported exchanges.

## Create Wallet

Create a new server wallet for a user. The wallet is secured with a 2-of-2 MPC threshold scheme.

### Endpoint

`POST /api/wallets`

### Request Body

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

| Field    | Type   | Required | Description                    |
| -------- | ------ | -------- | ------------------------------ |
| `userId` | string | Yes      | Unique identifier for the user |

### Response

```json theme={null}
{
  "success": true,
  "userId": "user_123",
  "address": "0x173404aAAa4d6539e2C7dbcC1931Cf41b3A3D5c7",
  "walletId": "29dd4dc0-1ff9-4df6-a19f-936f997cbc5a",
  "publicKey": "04090ce18936a64a24c48624d5734edf96d33a5f3d79bb014f27ebfa2197a813cfc46009ac278f4de56afc3e48733d1adf1a6cf804e6b20ddf55a9f5d4f651104a"
}
```

### Response Fields

| Field       | Type    | Description                                                 |
| ----------- | ------- | ----------------------------------------------------------- |
| `success`   | boolean | Operation status                                            |
| `userId`    | string  | User identifier (used for wallet lookup)                    |
| `address`   | string  | Wallet address (0x...) - needed for deposits & transactions |
| `walletId`  | string  | Wallet UUID - needed for API registration & signing         |
| `publicKey` | string  | Public key for verification                                 |

### Example Request

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

```javascript theme={null}
const response = await axios.post('https://api.tide.ag/api/wallets', {
  userId: 'user_123'
});
```

***

## Get Wallet

Retrieve wallet information by userId, walletId, or wallet address.

### Endpoint

`GET /api/wallets/:walletIdOrAddress`

### Path Parameters

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

### Example Requests

```bash theme={null}
# By userId
curl https://api.tide.ag/api/wallets/user_123

# By walletId
curl https://api.tide.ag/api/wallets/29dd4dc0-1ff9-4df6-a19f-936f997cbc5a

# By address
curl https://api.tide.ag/api/wallets/0x173404aAAa4d6539e2C7dbcC1931Cf41b3A3D5c7
```

### Response

```json theme={null}
{
  "success": true,
  "userId": "user_123",
  "address": "0x173404aAAa4d6539e2C7dbcC1931Cf41b3A3D5c7",
  "walletId": "29dd4dc0-1ff9-4df6-a19f-936f997cbc5a",
  "publicKey": "04090ce18936a64a24c48624d5734edf96d33a5f3d79bb014f27ebfa2197a813cfc46009ac278f4de56afc3e48733d1adf1a6cf804e6b20ddf55a9f5d4f651104a"
}
```

### Error Responses

**400 Bad Request**

```json theme={null}
{
  "error": "Missing wallet identifier"
}
```

**404 Not Found**

```json theme={null}
{
  "error": "Wallet not found"
}
```

***

## Sign Message

Sign an arbitrary message using the server wallet's MPC-managed key shares.

### Endpoint

`POST /api/wallets/:walletIdOrAddress/sign`

### Path Parameters

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

### Request Body

```json theme={null}
{
  "message": "Hello, World!"
}
```

| Field     | Type   | Required | Description     |
| --------- | ------ | -------- | --------------- |
| `message` | string | Yes      | Message to sign |

### Response

```json theme={null}
{
  "success": true,
  "signature": "0x5522633926941ce275ded2f02dec36b5c09532f0047542cbec35731338739403382ab7c700f01760238152ce9f594fe522ef79a86075a936f4e89a1f9baaa3f61c",
  "message": "Hello, World!"
}
```

### Example Request

```bash theme={null}
curl -X POST https://api.tide.ag/api/wallets/user_123/sign \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello, World!"}'
```

```javascript theme={null}
const response = await axios.post(
  'https://api.tide.ag/api/wallets/user_123/sign',
  { message: 'Hello, World!' }
);
```

### Error Responses

**400 Bad Request**

```json theme={null}
{
  "error": "Missing message"
}
```

**404 Not Found**

```json theme={null}
{
  "error": "Wallet not found"
}
```

**500 Internal Server Error**

```json theme={null}
{
  "error": "Failed to sign message"
}
```

***

## Security Features

* **MPC Key Management**: Wallets use 2-of-2 threshold signature scheme
* **Encrypted Storage**: Private key shares are encrypted at rest
* **No Single Point of Failure**: Key shares are distributed across multiple parties
* **Secure Signing**: All signing operations use MPC protocol

## Use Cases

* Create wallets for new users joining the platform
* Retrieve wallet information for trading operations
* Sign messages for exchange API registration
* Sign transactions for deposits and withdrawals

<Warning>
  Server wallets are managed by the platform. Never expose wallet credentials or private key shares to clients.
</Warning>

<Tip>
  Store the `walletId` and `address` returned from wallet creation. You'll need these for all subsequent trading operations.
</Tip>

## Environment Configuration

Required environment variables:

```bash theme={null}
DYNAMIC_AUTH_TOKEN=<your_dynamic_auth_token>
DYNAMIC_ENV_ID=<your_dynamic_environment_id>
WALLET_PASSWORD=<secure_password>
```

Get these credentials from [Dynamic Labs Dashboard](https://app.dynamic.xyz/dashboard/developer/api).


## OpenAPI

````yaml POST /api/wallets
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/wallets:
    post:
      tags:
        - Account
      summary: Create Server Wallet
      description: Create a new MPC-secured server wallet for a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWalletRequest'
            example:
              userId: user_123
      responses:
        '201':
          description: Wallet created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWalletResponse'
        '400':
          description: Bad request - missing userId
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing userId
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Failed to create wallet
      security: []
components:
  schemas:
    CreateWalletRequest:
      type: object
      required:
        - userId
      properties:
        userId:
          type: string
          description: Unique identifier for the user
          example: user_123
    CreateWalletResponse:
      type: object
      properties:
        success:
          type: boolean
        userId:
          type: string
          description: User identifier
        address:
          type: string
          description: Wallet address (0x...)
        walletId:
          type: string
          description: Wallet UUID
        publicKey:
          type: string
          description: Public key for verification
  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.

````