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

# Create Smart Account

> Create a new Smart Account

Create a new Smart Account with your desired configuration of signers, threshold, and optional settings. The Smart Account will be created on-chain and you'll receive its address in the response.

### Key Concepts

* **Signers and Permissions**: Each signer must have specific permissions (CAN\_INITIATE, CAN\_VOTE, CAN\_EXECUTE)
* **Threshold**: The minimum number of required signatures for any action
* **Optional Settings**: Configure an admin address to limit the ability to update the account's settings to only the admin address

### Idempotency

You can optionally provide an idempotency key via the `x-idempotency-key` header to prevent duplicate account creation. The idempotency key can be any random string and helps ensure that retrying the same request won't create multiple accounts.

When using idempotency:

* If an account was already created with the provided key → Returns status "created" and the existing account address
* If a request is still being processed → Returns status "pending" and an empty address
* If no idempotency key is provided → Creates a new account and returns status "created" with the new address

### Important Notes

* At least one signer must have CAN\_INITIATE permission
* The threshold cannot exceed the number of signers with CAN\_VOTE permission
* Use idempotency keys when retrying failed requests to prevent duplicate accounts
* The response status field indicates whether the account is ready to use
* Updating an account with an admin\_address set requires [admin mode](https://developers.squads.so/api-reference/v1/endpoint/smart-accounts/patch#admin-mode)


## OpenAPI

````yaml POST /api/v1/smart-accounts
openapi: 3.0.0
info:
  title: Squads API
  version: 1.0.0
  description: >
    The Squads API provides functionality for managing smart accounts and
    spending limits.

    This API allows you to create and manage smart accounts, set up spending
    limits, and perform transactions.
servers:
  - url: https://developer-api.squads.so
    description: Production server
security:
  - bearerAuth: []
paths:
  /api/v1/smart-accounts:
    post:
      summary: Create a new smart account
      operationId: createSmartAccount
      parameters:
        - $ref: '#/components/parameters/NetworkHeader'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - smart_account_signers
                - threshold
              properties:
                smart_account_signers:
                  type: array
                  items:
                    $ref: '#/components/schemas/Signer'
                  description: List of signers for the smart account
                threshold:
                  type: integer
                  format: uint32
                  description: Number of signatures required
                admin_address:
                  type: string
                  description: Optional admin address
                memo:
                  type: string
                  description: Optional memo
      responses:
        '200':
          description: Smart account creation request processed successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  smart_account_address:
                    type: string
                    description: >-
                      Address of the created smart account. Empty if status is
                      pending.
                  status:
                    type: string
                    enum:
                      - created
                      - pending
                    description: >-
                      Status of the account creation. 'created' indicates the
                      account is ready, 'pending' means it's still being
                      processed.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  parameters:
    NetworkHeader:
      name: x-squads-network
      in: header
      required: true
      schema:
        type: string
        enum:
          - mainnet
          - devnet
      description: Specifies the network for the API request
    IdempotencyKey:
      name: x-idempotency-key
      in: header
      required: false
      schema:
        type: string
      description: >-
        Optional idempotency key to prevent duplicate account creation. If
        provided, the API will return the same result for identical requests.
  schemas:
    Signer:
      type: object
      properties:
        address:
          type: string
          description: Address of the signer
        permissions:
          type: array
          items:
            type: string
            enum:
              - CAN_INITIATE
              - CAN_VOTE
              - CAN_EXECUTE
          description: List of permissions granted to the signer
    Error:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        code:
          type: string
          description: Error code for easy lookup
        message:
          type: string
          description: Detailed error description
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
        metadata:
          $ref: '#/components/schemas/ErrorMetadata'
        custom:
          type: object
          additionalProperties:
            type: string
        simulation_logs:
          type: array
          items:
            type: string
          description: >-
            Transaction simulation logs. Returns an empty array when debug=false
            or not provided.
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
          description: The field that failed validation
        code:
          type: string
          description: Error code specific to this validation failure
        message:
          type: string
          description: Detailed message about the validation failure
        expected:
          type: string
          description: Expected value or condition
        actual:
          type: string
          description: Actual value received
    ErrorMetadata:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        request_id:
          type: string
          description: Unique identifier for debugging
        timestamp:
          type: string
          format: date-time
          description: When the error occurred
        resource_id:
          type: string
          description: Identifier of the resource that experienced the error
        useful_links:
          type: array
          items:
            type: string
          description: Links to relevant documentation
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: UUID
      description: UUID-based API key provided by Squads

````