openapi: 3.1.0
info:
  title: Atto Wallet Server API
  description: >-
    The Atto Wallet Server provides a simple, self-hostable interface to manage
    accounts, send and receive funds, and track balances within the Atto
    network. It is designed for use by applications, abstracting away the
    complexity of directly interacting with the node.
  version: v1.0.0
externalDocs:
  description: Integration Docs
  url: https://atto.cash/docs/integration
servers:
  - url: http://localhost:8080
    description: Generated server url
tags:
  - name: Accounts
    description: >-
      Manage accounts within a wallet. This controller allows clients to create
      new accounts, enable or disable them, send transactions, and change a
      representative. Accounts are scoped to wallets and represent individual
      identities on the Atto network. This interface is designed for
      applications interacting with locally managed accounts.
  - name: Wallets
    description: >-
      Manage wallets in the self-hosted Atto Wallet Server. This controller
      allows you to create new wallets, import existing ones using mnemonics,
      lock and unlock wallets by managing their in-memory decryption keys, and
      list or retrieve wallet information. Designed for applications that
      require secure and programmatic control over local wallets.
paths:
  /wallets/{name}:
    get:
      tags:
        - Wallets
      summary: Get wallet metadata
      description: Retrieves metadata for the wallet identified by *name*.
      operationId: get
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/WalletState'
    put:
      tags:
        - Wallets
      summary: Import existing wallet
      description: >-
        Imports a wallet from its 24‑word mnemonic. You may supply your own Cha
        Cha 20 encryption key; if omitted, the server generates one. Losing
        either the mnemonic or key means permanent loss of access.
      operationId: import
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletImportRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/WalletCreationResponse'
    post:
      tags:
        - Wallets
      summary: Create a wallet
      description: >-
        Generates a brand‑new wallet with a fresh mnemonic and encryption key,
        both encrypted at rest. Losing either will lock the wallet forever.
      operationId: createWallet
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/WalletCreationResponse'
  /wallets/{name}/locks/UNLOCKED:
    put:
      tags:
        - Wallets
      summary: Unlock wallet
      description: >-
        Loads the provided encryptionKey into memory and stores it securely by
        encrypting it at rest using the `CHA_CHA20_KEY_ENCRYPTION_KEY`.
      operationId: unlock
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletUnlockRequest'
        required: true
      responses:
        '200':
          description: OK
          content: {}
  /wallets/{name}/locks/LOCKED:
    put:
      tags:
        - Wallets
      summary: Lock wallet
      description: >-
        Purges the decryption key for the wallet, preventing signing operations
        until it is unlocked again.
      operationId: lock
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content: {}
  /wallets/{walletName}/accounts:
    get:
      tags:
        - Accounts
      summary: Get accounts for given wallet
      operationId: findAll
      parameters:
        - name: walletName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Account'
    post:
      tags:
        - Accounts
      summary: Create an account
      operationId: create
      parameters:
        - name: walletName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AccountCreationResponse'
  /wallets/accounts/{address}/transactions/SEND:
    post:
      tags:
        - Accounts
      summary: Send to target address
      operationId: send
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AccountEntry'
  /wallets/accounts/{address}/transactions/CHANGE:
    post:
      tags:
        - Accounts
      summary: Change representative
      operationId: change
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AccountEntry'
  /wallets/accounts/{address}/states/ENABLED:
    post:
      tags:
        - Accounts
      summary: Enable an account
      operationId: enable
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content: {}
  /wallets/accounts/{address}/states/DISABLED:
    post:
      tags:
        - Accounts
      summary: Disable an account
      operationId: disable
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content: {}
  /wallets/accounts/entries:
    post:
      tags:
        - Accounts
      summary: Get account entries
      operationId: search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeightSearch'
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AccountEntry'
  /wallets:
    get:
      tags:
        - Wallets
      summary: List all wallets
      description: >-
        Lists every wallet stored on the server together with its current lock
        state.
      operationId: list
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/WalletState'
  /wallets/accounts/{address}:
    get:
      tags:
        - Accounts
      summary: Get account
      operationId: get_1
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Account'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Account'
  /wallets/accounts/{address}/details:
    get:
      tags:
        - Accounts
      summary: Get account details
      operationId: getDetails
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AccountDetails'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AccountDetails'
components:
  schemas:
    WalletImportRequest:
      type: object
      description: Represents a request to import an wallet
      properties:
        mnemonic:
          type: string
          description: 24 words mnemonic
          example: >-
            florbit nuster glenth ravax drindle sporkel quenth brimzo kraddle
            yempth plarnix chuzzle grintop vornish daprex slindle frumple zorgat
            mekton yindle cravix blanter swooshle prindle
        encryptionKey:
          type: string
          description: >-
            Optional 32 bytes hex encoded Cha Cha 20 encryption key used to
            encrypt mnemonic at rest. If not provided the wallet will generate
            one.
          example: '0000000000000000000000000000000000000000000000000000000000000000'
      required:
        - mnemonic
    WalletCreationResponse:
      type: object
      description: Represents a request to create an wallet
      properties:
        mnemonic:
          type: string
          description: 24 words mnemonic
          example: >-
            florbit nuster glenth ravax drindle sporkel quenth brimzo kraddle
            yempth plarnix chuzzle grintop vornish daprex slindle frumple zorgat
            mekton yindle cravix blanter swooshle prindle
        encryptionKey:
          type: string
          description: >-
            32 bytes hex encoded Cha Cha 20 encryption key used to encrypt
            mnemonic at rest
          example: '0000000000000000000000000000000000000000000000000000000000000000'
      required:
        - encryptionKey
        - mnemonic
    WalletUnlockRequest:
      type: object
      description: Represents a request to unlock the wallet
      properties:
        encryptionKey:
          type: string
          description: >-
            32 bytes hex encoded Cha Cha 20 encryption key used to encrypt
            mnemonic at rest
          example: '0000000000000000000000000000000000000000000000000000000000000000'
      required:
        - encryptionKey
    AccountCreationResponse:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AttoAddress'
        displayAddress:
          type: string
        index:
          type: integer
          format: int32
      required:
        - address
        - displayAddress
        - index
    AttoAddress:
      type: object
      properties:
        algorithm:
          type: string
          enum:
            - V1
        publicKey:
          $ref: '#/components/schemas/AttoPublicKey'
        schema:
          type: string
        path:
          type: string
        value:
          type: string
      required:
        - algorithm
        - path
        - publicKey
        - schema
        - value
    AttoPublicKey:
      type: object
      properties:
        value:
          type: string
          format: byte
      required:
        - value
    SendRequest:
      type: object
      properties:
        receiverAddress:
          type: string
          description: The address of the receiving account
          example: aa36n56jj5scb5ssb42knrtl7bgp5aru2v6pd2jspj5axdw2iukun6r2du4k2
        amount:
          type: integer
          format: int64
          description: Amount
          example: 10000
        lastHeight:
          type: integer
          format: int64
          description: Optional last known height. Used to avoid double sent
          example: 1
      required:
        - amount
        - receiverAddress
    AccountEntry:
      type: object
      description: An user-friendly view of account activity
      properties:
        hash:
          type: string
          description: Unique hash of the block
          example: 68BA42CDD87328380BE32D5AA6DBB86E905B50273D37AF1DE12F47B83A001154
        address:
          type: string
          description: Address of the account
          example: aa36n56jj5scb5ssb42knrtl7bgp5aru2v6pd2jspj5axdw2iukun6r2du4k2
        height:
          type: integer
          format: int64
          description: Block height
          example: 0
        blockType:
          type: string
          description: Type of block in the account chain
          enum:
            - UNKNOWN
            - OPEN
            - RECEIVE
            - SEND
            - CHANGE
          example: RECEIVE
        subjectAddress:
          $ref: '#/components/schemas/AttoAddress'
          description: Address of the subject involved in the transaction
          example: aa36n56jj5scb5ssb42knrtl7bgp5aru2v6pd2jspj5axdw2iukun6r2du4k2
        previousBalance:
          $ref: '#/components/schemas/AttoAmount'
          description: Public key of the subject involved in the transaction
          example: 2EB21717813E7A0E0A7E308B8E2FD8A051F8724F5C5F0047E92E19310C582E3A
        balance:
          $ref: '#/components/schemas/AttoAmount'
          description: Balance before this block
          example: 0
        timestamp:
          $ref: '#/components/schemas/Instant'
          description: Balance after this block
          example: 100
      required:
        - address
        - balance
        - blockType
        - hash
        - height
        - previousBalance
        - subjectAddress
        - timestamp
    AttoAmount:
      type: object
      properties:
        raw:
          type: integer
          format: int64
      required:
        - raw
    Instant:
      type: object
      properties:
        value:
          type: string
          format: date-time
          writeOnly: true
        epochSeconds:
          type: integer
          format: int64
        nanosecondsOfSecond:
          type: integer
          format: int32
        value$kotlinx_datetime:
          type: string
          format: date-time
      required:
        - epochSeconds
        - nanosecondsOfSecond
        - value$kotlinx_datetime
    ChangeRequest:
      type: object
      properties:
        representativeAddress:
          type: string
          description: The address of the new representative account
          example: aa36n56jj5scb5ssb42knrtl7bgp5aru2v6pd2jspj5axdw2iukun6r2du4k2
      required:
        - representativeAddress
    AccountHeightSearch:
      type: object
      properties:
        address:
          type: string
          description: The address of the account being searched
          example: aa36n56jj5scb5ssb42knrtl7bgp5aru2v6pd2jspj5axdw2iukun6r2du4k2
        fromHeight:
          type: integer
          format: int64
      required:
        - address
        - fromHeight
    HeightSearch:
      type: object
      properties:
        search:
          type: array
          items:
            $ref: '#/components/schemas/AccountHeightSearch'
      required:
        - search
    WalletState:
      type: object
      description: View of the current wallet state
      properties:
        name:
          type: string
        lockState:
          type: string
          enum:
            - LOCKED
            - UNLOCKED
      required:
        - lockState
        - name
    Account:
      type: object
      properties:
        address:
          type: string
          description: The address of the account
          example: aa36n56jj5scb5ssb42knrtl7bgp5aru2v6pd2jspj5axdw2iukun6r2du4k2
        version:
          type: integer
          format: int64
          description: The database version of the row used for optimistic locking
          example: 1
        accountIndex:
          type: integer
          format: int64
          description: The index of the account in the mnemonic
          example: 1
        walletName:
          type: string
          description: Wallet name
          example: treasury
        disabledAt:
          type: string
          format: date-time
          description: Timestamp when the account was disabled
          example: treasury
      required:
        - accountIndex
        - address
        - walletName
    AccountDetails:
      type: object
      properties:
        address:
          type: string
          description: The address of the account
          example: aa36n56jj5scb5ssb42knrtl7bgp5aru2v6pd2jspj5axdw2iukun6r2du4k2
        version:
          type: integer
          format: int32
          description: Version
          example: 0
        height:
          type: integer
          format: int64
          description: Height
          example: 1
        balance:
          type: integer
          format: int64
          description: Balance
          example: 180000000000
        lastTransactionHash:
          type: string
          description: Last transaction hash
          example: 70F9406609BCB2E3E18F22BD0839C95E5540E95489DC6F24DBF6A1F7CFD83A92
        lastTransactionTimestamp:
          type: integer
          format: int64
          description: Timestamp of the last transaction
          example: 1705517157478
        representativeAddress:
          type: string
          description: Representative algorithm
          example: aa36n56jj5scb5ssb42knrtl7bgp5aru2v6pd2jspj5axdw2iukun6r2du4k2
      required:
        - address
        - balance
        - height
        - lastTransactionHash
        - lastTransactionTimestamp
        - representativeAddress
        - version