gru_emoney_token-factory/api/packages/openapi/v1/paths/tokens.yaml

paths:
  /tokens:
    post:
      summary: Deploy a new token
      description: Deploy a new eMoney token on ChainID 138
      operationId: deployToken
      tags:
        - Tokens
      security:
        - oauth2:
            - tokens:write
      x-roles:
        - TOKEN_DEPLOYER
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/components/schemas/DeployTokenRequest'
            examples:
              usdw:
                $ref: '../examples/tokens.yaml#/components/examples/DeployUSDW'
      responses:
        '201':
          description: Token deployed successfully
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Token'
        '400':
          $ref: '../openapi.yaml#/components/responses/BadRequest'
        '401':
          $ref: '../openapi.yaml#/components/responses/Unauthorized'
        '403':
          $ref: '../openapi.yaml#/components/responses/Forbidden'
        '409':
          $ref: '../openapi.yaml#/components/responses/Conflict'
    
    get:
      summary: List tokens
      description: List all deployed tokens with optional filtering
      operationId: listTokens
      tags:
        - Tokens
      security:
        - oauth2:
            - tokens:read
      parameters:
        - name: code
          in: query
          schema:
            type: string
            pattern: '^[A-Z0-9]{1,10}$'
          description: Filter by token code
        - name: issuer
          in: query
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
          description: Filter by issuer address
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Pagination offset
      responses:
        '200':
          description: List of tokens
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '../components/schemas.yaml#/components/schemas/Token'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer

  /tokens/{code}:
    get:
      summary: Get token metadata
      description: Get token metadata and configuration by code
      operationId: getToken
      tags:
        - Tokens
      security:
        - oauth2:
            - tokens:read
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
      responses:
        '200':
          description: Token metadata
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Token'
        '404':
          $ref: '../openapi.yaml#/components/responses/NotFound'

    patch:
      summary: Update token policy
      description: Update token policy configuration (pause, lienMode, bridgeOnly, etc.)
      operationId: updateTokenPolicy
      tags:
        - Tokens
      security:
        - oauth2:
            - tokens:write
      x-roles:
        - POLICY_OPERATOR
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/components/schemas/UpdatePolicyRequest'
      responses:
        '200':
          description: Policy updated
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Token'

  /tokens/{code}/mint:
    post:
      summary: Mint tokens
      description: Mint new tokens to an address (requires ISSUER_ROLE)
      operationId: mintTokens
      tags:
        - Tokens
      security:
        - oauth2:
            - tokens:write
      x-roles:
        - ISSUER
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/components/schemas/MintRequest'
      responses:
        '200':
          description: Tokens minted
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/TransactionResponse'

  /tokens/{code}/burn:
    post:
      summary: Burn tokens
      description: Burn tokens from an address (requires ISSUER_ROLE)
      operationId: burnTokens
      tags:
        - Tokens
      security:
        - oauth2:
            - tokens:write
      x-roles:
        - ISSUER
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/components/schemas/BurnRequest'
      responses:
        '200':
          description: Tokens burned
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/TransactionResponse'

  /tokens/{code}/clawback:
    post:
      summary: Clawback tokens
      description: Clawback tokens from an address (requires ENFORCEMENT_ROLE)
      operationId: clawbackTokens
      tags:
        - Tokens
      security:
        - oauth2:
            - tokens:write
      x-roles:
        - ENFORCEMENT
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/components/schemas/ClawbackRequest'
      responses:
        '200':
          description: Tokens clawed back
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/TransactionResponse'

  /tokens/{code}/force-transfer:
    post:
      summary: Force transfer tokens
      description: Force transfer tokens between addresses (requires ENFORCEMENT_ROLE and forceTransferMode)
      operationId: forceTransferTokens
      tags:
        - Tokens
      security:
        - oauth2:
            - tokens:write
      x-roles:
        - ENFORCEMENT
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TokenCode'
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/components/schemas/ForceTransferRequest'
      responses:
        '200':
          description: Tokens force transferred
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/TransactionResponse'