# Accounts and Signers

A wallet owns one or more subaccounts. A subaccount contains balances, margin pools, orders, positions, and linked signers.

## Subaccount Identity

The onchain identity is the owner address plus a bytes32 name. The API also assigns a UUID in `id`.

Use:

* The bytes32 name in signed messages.
* The UUID in query parameters such as `subaccountId`.
* The owner address in `sender` when you list the owner's subaccounts.

The default application name is usually `primary`, encoded as UTF-8 and right-padded with zeros to 32 bytes.

## Create a Subaccount

The public API does not have a separate create endpoint. A valid first deposit creates and registers the first subaccount for an owner. Later deposits can fund an existing subaccount.

Registration is an onchain action. The API can show a new record before `registeredBlockNumber` is available. Wait for registration before you submit a trade.

## Query Subaccounts

List subaccounts for an owner:

```http
GET /v1/subaccount?sender=0xOWNER_ADDRESS
```

Get one subaccount:

```http
GET /v1/subaccount/{id}
```

List its balances:

```http
GET /v1/subaccount/balance?subaccountId=SUBACCOUNT_UUID
```

Each balance item contains `amount`, `available`, and `totalUsed`. Balances with different `tokenId` values are different margin pools.

## Linked Signers

A linked signer is an EOA key that can act for one subaccount. It supports one-click trading and automated integrations.

A linked signer can:

* Submit and cancel orders.
* Sign an internal token conversion.
* Use private account data when the endpoint accepts linked-signer authentication.

A linked signer cannot withdraw funds or change account ownership. The owner wallet keeps withdrawal authority.

## Link a Signer

```http
POST /v1/linked-signer/link
```

The `LinkSigner` message contains the owner address, signer address, subaccount name, nonce, and signing time. Both the owner and the new signer sign the same message. Send the signatures as `signature` and `signerSignature`.

The request also contains `subaccountId`. Optional metadata fields are `name` and `category`.

Important restrictions:

* A signer address can be linked only once.
* A revoked signer address cannot be linked again.
* A signer cannot already own a subaccount.
* A current or former system account cannot be a linked signer.
* Active and time-period quotas apply.

Create a new signer key if an old signer is revoked or compromised.

## Quotas

Get the current quota for a subaccount:

```http
GET /v1/linked-signer/quota?subaccountId=SUBACCOUNT_UUID
```

Quota values are configuration. Do not hard-code them.

## Expiry

Each linked signer has `expiresAt`. The configured expiry period and renewal window can change.

Two renewal flows exist:

* `POST /v1/linked-signer/extend` uses a signature from the active linked signer.
* `POST /v1/linked-signer/refresh` uses a signature from the owner and can restore an expired signer.

Renewal is accepted only within the configured renewal window. Query the signer and use `expiresAt` instead of assuming a fixed number of days.

## Revoke a Signer

```http
DELETE /v1/linked-signer/revoke
```

The owner signs `RevokeLinkedSigner`. Cancel all working orders that the signer created before revocation. This prevents an offchain fill from becoming impossible to settle after the onchain signer is revoked.

Revocation is permanent for that signer address.

## Query Signers

* `GET /v1/linked-signer?subaccountId=<uuid>` lists signers for a subaccount.
* `GET /v1/linked-signer/{id}` gets a signer by UUID.
* `GET /v1/linked-signer/address/{address}` gets a signer by address.
* `GET /v1/linked-signer/quota` returns the current quota.

## Key Safety

* Generate the linked-signer key on the user's device.
* Do not send the private key to Meridian.
* Store it in secure device storage.
* Use a separate key for each device or automated system.
* Revoke a signer if the device or key is lost.
* Do not use the owner wallet key as a linked-signer key.

See [Message Signing](/developer-guides/trading-api/message-signing) for EIP-712 examples.