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

# Create Partner Sub-Account

> Creates a new sub-account linked to the authenticated partner. Requires HMAC authentication with the `account_creation` scope.

**Server wallet mode** (`createServerWallet: true`): Creates a Privy server wallet and profile. The partner can then submit orders on behalf of this account using delegated signing.

**EOA mode** (default): Requires wallet ownership verification via `x-account`, `x-signing-message`, and `x-signature` headers. The end user signs their own orders.

<Info>
  Requires **HMAC authentication** with the `account_creation` scope. API key auth and Privy auth are not accepted.
</Info>

Creates a new sub-account profile linked to the authenticated partner.

If account creation succeeds but your app fails to persist the returned
`profileId`, use [List Partner Sub-Accounts](/api-reference/partner-accounts/list-partner-accounts)
with the `account` filter to recover it.

### Server wallet mode

Set `createServerWallet: true` to create a Privy server wallet for the sub-account. This enables [delegated signing](/developers/authentication#delegated-signing) — the partner can submit unsigned orders and the server signs them using the managed wallet.

Before the first delegated trade, call [Check Partner Account Allowances](/api-reference/partner-accounts/check-allowances). If any target is `missing` or `failed` with `retryable=true`, call [Retry Partner Account Allowances](/api-reference/partner-accounts/retry-allowances), then poll the check endpoint again.

<Warning>
  Server wallet creation requires the `delegated_signing` scope on your API token (in addition to `account_creation`). Without it, the request returns `"Server wallet creation requires delegated_signing scope"`.
</Warning>

```json theme={null}
{
  "displayName": "user-bob",
  "createServerWallet": true
}
```

### EOA mode

Omit `createServerWallet` (or set it to `false`) to create an account for an externally-owned address. The end user manages their own keys and signs their own orders.

EOA mode requires three additional headers for wallet ownership verification:

| Header              | Description                                                           |
| ------------------- | --------------------------------------------------------------------- |
| `x-account`         | Checksummed Ethereum address (EIP-55)                                 |
| `x-signing-message` | Hex-encoded signing message obtained from `GET /auth/signing-message` |
| `x-signature`       | Hex-encoded signature produced by signing the message with the wallet |

#### Signing message format

The `x-signing-message` value is **not** the raw text — it is the **hex-encoded** UTF-8 representation of the message returned by `GET /auth/signing-message`. The raw text (which you sign) looks like:

```
Welcome to Limitless Exchange!

This request will not trigger a blockchain transaction or cost any gas fees.

Signature is required to authenticate an upcoming API request.

Nonce: 0x<keccak256-hash>
```

The full flow:

1. **Fetch** the signing message: `GET /auth/signing-message` → returns the plain-text message with a unique nonce.
2. **Sign** the plain-text message with the wallet (e.g. `personal_sign` / `eth_sign`).
3. **Hex-encode** the plain-text message: prepend `0x` to the UTF-8 hex representation.
4. **Send** all three headers on the request.

<CodeGroup>
  ```python Python theme={null}
  import requests
  from eth_account import Account
  from eth_account.messages import encode_defunct

  # 1. Fetch the signing message
  signing_message = requests.get(f"{API_BASE_URL}/auth/signing-message").text

  # 2. Sign the plain-text message
  message = encode_defunct(text=signing_message)
  signed = account.sign_message(message)

  # 3. Hex-encode the message for the header
  hex_message = "0x" + signing_message.encode("utf-8").hex()

  # 4. Use in headers
  headers = {
      "x-account": account.address,                # checksummed address
      "x-signing-message": hex_message,             # hex-encoded message
      "x-signature": "0x" + signed.signature.hex(), # hex-encoded signature
  }
  ```

  ```typescript TypeScript theme={null}
  import { createWalletClient, http, toHex } from 'viem';
  import { privateKeyToAccount } from 'viem/accounts';
  import { base } from 'viem/chains';

  // 1. Fetch the signing message
  const signingMessage = await fetch(`${API_BASE_URL}/auth/signing-message`).then(r => r.text());

  // 2. Sign the plain-text message
  const account = privateKeyToAccount(PRIVATE_KEY);
  const signature = await account.signMessage({ message: signingMessage });

  // 3. Hex-encode the message for the header
  const hexMessage = toHex(new TextEncoder().encode(signingMessage));

  // 4. Use in headers
  const headers = {
    'x-account': account.address,      // checksummed address
    'x-signing-message': hexMessage,   // hex-encoded message
    'x-signature': signature,          // hex-encoded signature
  };
  ```
</CodeGroup>

```json theme={null}
{
  "displayName": "user-alice"
}
```

### Constraints

* `displayName` is optional (max 44 characters). Defaults to the wallet address if omitted.
* Returns `409 Conflict` if a profile already exists for the target address.
* Cannot create a sub-account for the partner's own address.


## OpenAPI

````yaml POST /profiles/partner-accounts
openapi: 3.0.0
info:
  title: Limitless Exchange API
  description: >-
    Production-ready REST API for prediction market trading, portfolio
    management, and market data on Limitless Exchange (Base L2).
  version: '1.0'
  contact:
    name: API Support
    url: https://limitless.exchange
    email: help@limitless.network
servers:
  - url: https://api.limitless.exchange
    description: Production API
security: []
tags:
  - name: Authentication
    description: User authentication and session management
  - name: Markets
    description: Browse, search, and analyze prediction markets
  - name: Market Navigation
    description: Navigation tree, market pages, and property filters
  - name: Trading
    description: Create, manage, and cancel orders
  - name: Portfolio
    description: Position tracking, trade history, and performance
  - name: API Tokens
    description: Scoped API token management for partner integrations
  - name: Partner Accounts
    description: Sub-account creation and allowance recovery for partner integrations
  - name: System
    description: Public API state and availability information
paths:
  /profiles/partner-accounts:
    post:
      tags:
        - Partner Accounts
      summary: Create partner sub-account
      description: >-
        Creates a new sub-account linked to the authenticated partner. Requires
        HMAC authentication with the `account_creation` scope.


        **Server wallet mode** (`createServerWallet: true`): Creates a Privy
        server wallet and profile. The partner can then submit orders on behalf
        of this account using delegated signing.


        **EOA mode** (default): Requires wallet ownership verification via
        `x-account`, `x-signing-message`, and `x-signature` headers. The end
        user signs their own orders.
      operationId: ProfileController_createPartnerAccount
      parameters:
        - name: x-account
          in: header
          required: false
          schema:
            type: string
          description: >-
            EOA mode only. Checksummed Ethereum address of the sub-account
            wallet.
        - name: x-signing-message
          in: header
          required: false
          schema:
            type: string
          description: EOA mode only. Hex-encoded signing message.
        - name: x-signature
          in: header
          required: false
          schema:
            type: string
          description: EOA mode only. Hex-encoded signature from the sub-account wallet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePartnerAccountRequest'
      responses:
        '201':
          description: Sub-account created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePartnerAccountResponse'
        '400':
          description: >-
            Cannot create a partner account for the partner's own address, or
            profile creation failed
        '401':
          description: Wallet ownership verification failed (EOA mode)
        '403':
          description: Requires apiToken auth with account_creation scope
        '409':
          description: A profile already exists for this address
      security:
        - HmacAuth: []
components:
  schemas:
    CreatePartnerAccountRequest:
      type: object
      properties:
        displayName:
          type: string
          maxLength: 44
          description: >-
            Public display name for the sub-account. Defaults to the wallet
            address if omitted.
          example: user-alice
        createServerWallet:
          type: boolean
          description: >-
            If true, creates a Privy server wallet for the sub-account (enables
            delegated signing). If false or omitted, requires EOA wallet
            ownership headers.
          default: false
    CreatePartnerAccountResponse:
      type: object
      properties:
        profileId:
          type: integer
          description: Profile ID of the created sub-account
          example: 789
        account:
          type: string
          description: Wallet address of the created sub-account
          example: '0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed'
      required:
        - profileId
        - account
  securitySchemes:
    HmacAuth:
      type: apiKey
      in: header
      name: lmts-api-key
      description: >-
        Scoped API token with HMAC-SHA256 signing. Requires three headers:
        lmts-api-key (token ID), lmts-timestamp (ISO-8601), lmts-signature
        (Base64-encoded HMAC). See Authentication docs for details.

````