# Sub-Accounts
Create sub-accounts (no independent private key, controlled by main) or build voluntary associations between independent addresses (broker pattern).
## Create Sub-Account
> Main-account private-key signature. The chain generates a new address as a sub-account.\
> Sub-accounts have \*\*no independent private key\*\* — the main account has full control.\
> \
> Signing Method B, type:\
> \`CreateSubAccount(address sender,string label,uint64 nonce,uint64 expiresAfter)\`.\
> \
> \### Validation\
> \
> \- Signer must be a main account (not a sub-account)\
> \- Sub-account count must be below the VIP-tier-determined limit
```json
{"openapi":"3.0.3","info":{"title":"Lynx DEX API","version":"1.5.0"},"tags":[{"name":"Sub-Accounts","description":"Create sub-accounts (no independent private key, controlled by the main account) and query\nthe account hierarchy.\n"}],"servers":[{"url":"http://10.34.8.77:8481/v1","description":"Production"}],"paths":{"/account/create-sub":{"post":{"tags":["Sub-Accounts"],"summary":"Create Sub-Account","operationId":"createSubAccount","description":"Main-account private-key signature. The chain generates a new address as a sub-account.\nSub-accounts have **no independent private key** — the main account has full control.\n\nSigning Method B, type:\n`CreateSubAccount(address sender,string label,uint64 nonce,uint64 expiresAfter)`.\n\n### Validation\n\n- Signer must be a main account (not a sub-account)\n- Sub-account count must be below the VIP-tier-determined limit\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label","address","nonce","expires_after","signature"],"properties":{"label":{"type":"string","description":"Unique within the main account."},"address":{"type":"string"},"nonce":{"type":"integer","format":"int64"},"expires_after":{"type":"integer","format":"int64"},"signature":{"$ref":"#/components/schemas/Signature"}}}}}},"responses":{"200":{"description":"Sub-account created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"tx_hash":{"type":"string"},"sub_address":{"type":"string"},"label":{"type":"string"}}}}}]}}}},"422":{"description":"Errors: `20014` (signer cannot create sub), `20015` (label exists), `20017` (limit)"}}}}},"components":{"schemas":{"Signature":{"type":"object","description":"ECDSA signature components `(r, s, v)` over the EIP-712 signing hash.","required":["r","s","v"],"properties":{"r":{"type":"string","description":"32-byte hex string with `0x` prefix."},"s":{"type":"string","description":"32-byte hex string with `0x` prefix."},"v":{"type":"integer","description":"Recovery identifier — typically 27 or 28.","enum":[27,28]}}},"ResponseEnvelope":{"type":"object","description":"Standard response envelope shared by every endpoint.","required":["code","msg","data"],"properties":{"code":{"type":"string","description":"`\"0\"` for success. Non-zero indicates an error code — see [Error Codes](/reference/error-codes)."},"msg":{"type":"string","description":"Empty on success; human-readable error description on failure."},"data":{"description":"Endpoint-specific payload on success; `null` on failure.","nullable":true},"trace_code":{"type":"string","description":"Backend trace identifier. Empty on success; populated on failure for support diagnostics."}}}}}}
```
## List Children (Sub-Accounts)
> All sub-accounts under a main account.
```json
{"openapi":"3.0.3","info":{"title":"Lynx DEX API","version":"1.5.0"},"tags":[{"name":"Sub-Accounts","description":"Create sub-accounts (no independent private key, controlled by the main account) and query\nthe account hierarchy.\n"}],"servers":[{"url":"http://10.34.8.77:8481/v1","description":"Production"}],"paths":{"/account/children":{"get":{"tags":["Sub-Accounts"],"summary":"List Children (Sub-Accounts)","operationId":"listChildren","description":"All sub-accounts under a main account.","parameters":[{"$ref":"#/components/parameters/AddressQuery"}],"responses":{"200":{"description":"Children list","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/AccountChild"}}}}}}]}}}}}}}},"components":{"parameters":{"AddressQuery":{"name":"address","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"description":"Account address (`0x`-prefixed hex)."}},"schemas":{"ResponseEnvelope":{"type":"object","description":"Standard response envelope shared by every endpoint.","required":["code","msg","data"],"properties":{"code":{"type":"string","description":"`\"0\"` for success. Non-zero indicates an error code — see [Error Codes](/reference/error-codes)."},"msg":{"type":"string","description":"Empty on success; human-readable error description on failure."},"data":{"description":"Endpoint-specific payload on success; `null` on failure.","nullable":true},"trace_code":{"type":"string","description":"Backend trace identifier. Empty on success; populated on failure for support diagnostics."}}},"AccountChild":{"type":"object","properties":{"address":{"type":"string"},"type":{"type":"string","enum":["sub"]},"label":{"type":"string","description":"Sub-account label (only present when `type=sub`)."},"linked_at":{"type":"integer","format":"int64"}}}}}}
```
## Get Main Account
> For a sub-account, returns its main account. Returns \`null\` for an unrelated address.
```json
{"openapi":"3.0.3","info":{"title":"Lynx DEX API","version":"1.5.0"},"tags":[{"name":"Sub-Accounts","description":"Create sub-accounts (no independent private key, controlled by the main account) and query\nthe account hierarchy.\n"}],"servers":[{"url":"http://10.34.8.77:8481/v1","description":"Production"}],"paths":{"/account/main":{"get":{"tags":["Sub-Accounts"],"summary":"Get Main Account","operationId":"getMainAccount","description":"For a sub-account, returns its main account. Returns `null` for an unrelated address.","parameters":[{"$ref":"#/components/parameters/AddressQuery"}],"responses":{"200":{"description":"Main account (or null)","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"main_address":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"enum":["sub",null]}}}}}]}}}}}}}},"components":{"parameters":{"AddressQuery":{"name":"address","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"description":"Account address (`0x`-prefixed hex)."}},"schemas":{"ResponseEnvelope":{"type":"object","description":"Standard response envelope shared by every endpoint.","required":["code","msg","data"],"properties":{"code":{"type":"string","description":"`\"0\"` for success. Non-zero indicates an error code — see [Error Codes](/reference/error-codes)."},"msg":{"type":"string","description":"Empty on success; human-readable error description on failure."},"data":{"description":"Endpoint-specific payload on success; `null` on failure.","nullable":true},"trace_code":{"type":"string","description":"Backend trace identifier. Empty on success; populated on failure for support diagnostics."}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.lynxtrade.world/rest-api/sub-accounts.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.