auth.v1.SubaccountService

CreateSubaccount

Create a new sub-account under the caller's root account. Requires current terms acceptance; otherwise FailedPrecondition with AUTH_TERMS_NOT_ACCEPTED is returned.

Method

POST

Path

auth.v1.SubaccountService/CreateSubaccount

Service

auth.v1.SubaccountService

Visibility

Authentication required

Authentication

Session token

MFA Requirement

Not required

POST

auth.v1.SubaccountService/CreateSubaccount

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/auth.v1.SubaccountService/CreateSubaccount' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "color": "#7C3AED",
  "icon": "💰",
  "label": "Market Making",
  "message": "Polyester account authorization\n\nCreate a sub-account controlled by the smart account below.\nThis does not authorize a transaction or a login.\n\naction: create_subaccount\norigin: https://devnet.polyester.com\naudience: devnet\npolyester_chain_id: 888168\nroot_account_id: 123456789\nowner_address: 0x5555555555555555555555555555555555555555\nsmart_account_address: 0x2222222222222222222222222222222222222222\nsalt_nonce: 1\nrequest_id: 8f3a72c91b4de6058f3a72c91b4de6058f3a72c91b4de6058f3a72c91b4de605\nissued_at: 2026-01-01T00:00:00Z\nexpiration: 2026-01-01T00:05:00Z",
  "signature": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
  "smartAccountAddress": "0x2222222222222222222222222222222222222222"
}'

Responses

{
  "revision": "1",
  "smartAccountSaltNonce": 1,
  "subaccountId": "6789012345678",
  "totalCreated": 1
}

Request

auth.v1.CreateSubaccountRequest

Response

auth.v1.CreateSubaccountResponse

label string max 64 chars

Optional human label for display in UI.

icon string max 32 chars

Optional user-chosen icon/emoji for UI display.

color string (color) max 32 chars

Optional user-chosen color token for UI display. Tokens use lowercase letters, numbers, underscores, or hyphens.

smartAccountAddress string exactly 42 chars /^0x[0-…]{40}$/

Smart Account EVM address for the new sub-account.

message string min 1 chars

Exact EIP-191 authorization returned by CreateSubaccountChallenge. Maximum length is 4096 UTF-8 bytes.

signature string 1-8192 chars

Smart-account signature over message using EIP-191 personal_sign semantics. Deployed ERC-1271 and counterfactual ERC-6492 signatures are supported.

subaccountId string (fixed64)

Identifier for the created sub-account (opaque ID).

totalCreated integer (int32)

Total number of sub-accounts that have ever been created for this root, including soft-deleted ones. Request a new challenge for the next account.

smartAccountSaltNonce integer (int32)

Smart-account derivation salt nonce assigned to the created sub-account. Today this equals total_created for a successful create.

revision string (uint64)

Initial monotonic resource revision. Clients can pass this value directly as expected_revision on the next revision-gated mutation.

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.

POST

auth.v1.SubaccountService/CreateSubaccount

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/auth.v1.SubaccountService/CreateSubaccount' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "color": "#7C3AED",
  "icon": "💰",
  "label": "Market Making",
  "message": "Polyester account authorization\n\nCreate a sub-account controlled by the smart account below.\nThis does not authorize a transaction or a login.\n\naction: create_subaccount\norigin: https://devnet.polyester.com\naudience: devnet\npolyester_chain_id: 888168\nroot_account_id: 123456789\nowner_address: 0x5555555555555555555555555555555555555555\nsmart_account_address: 0x2222222222222222222222222222222222222222\nsalt_nonce: 1\nrequest_id: 8f3a72c91b4de6058f3a72c91b4de6058f3a72c91b4de6058f3a72c91b4de605\nissued_at: 2026-01-01T00:00:00Z\nexpiration: 2026-01-01T00:05:00Z",
  "signature": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
  "smartAccountAddress": "0x2222222222222222222222222222222222222222"
}'

Responses

{
  "revision": "1",
  "smartAccountSaltNonce": 1,
  "subaccountId": "6789012345678",
  "totalCreated": 1
}