Safe (Gnosis Safe) safes API

openapi: 3.1.0
info:
  title: Safe Transaction Service 4337 safes API
  version: 6.3.0
  description: API to keep track of transactions sent via Safe smart contracts
tags:
- name: safes
paths:
  /tx-service/eth/api/v1/safes/{address}/:
    get:
      operationId: safes_retrieve
      description: Returns detailed information of a given Safe account
      parameters:
      - in: path
        name: address
        schema:
          type: string
        required: true
      tags:
      - safes
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SafeInfoResponse'
          description: ''
        '404':
          description: Safe not found
        '422':
          description: 'code = 1: Checksum address validation failed

            code = 50: Cannot get Safe info'
      path: /tx-service/eth/api/v1/safes/{address}/
      title: Get Safe Status
      additionalInfo: ''
  /tx-service/eth/api/v1/safes/{address}/balances/:
    get:
      operationId: safes_balances_retrieve
      description: Get balance for Ether and ERC20 tokens of a given Safe account
      parameters:
      - in: path
        name: address
        schema:
          type: string
        required: true
      - in: query
        name: trusted
        schema:
          type: boolean
          default: false
        description: If `True` just trusted tokens will be returned
      - in: query
        name: exclude_spam
        schema:
          type: boolean
          default: false
        description: If `True` spam tokens will not be returned
      tags:
      - safes
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SafeBalanceResponse'
          description: ''
        '404':
          description: Safe not found
        '422':
          description: Safe address checksum not valid
      path: /tx-service/eth/api/v1/safes/{address}/balances/
      title: List a Safe's Balances (Deprecated)
      additionalInfo: ''
  /tx-service/eth/api/v1/safes/{address}/creation/:
    get:
      operationId: safes_creation_retrieve
      description: 'Returns detailed information on the Safe creation transaction of a given Safe.


        Note: When event indexing is being used and multiple Safes are deployed in the same transaction

        the result might not be accurate due to the indexer not knowing which events belong to which Safe

        deployment.'
      parameters:
      - in: path
        name: address
        schema:
          type: string
        required: true
      tags:
      - safes
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SafeCreationInfoResponse'
          description: ''
        '404':
          description: Safe creation not found
        '422':
          description: Owner address checksum not valid
        '503':
          description: Problem connecting to Ethereum network
      path: /tx-service/eth/api/v1/safes/{address}/creation/
      title: Get Safe Creation Status
      additionalInfo: ''
  /tx-service/eth/api/v1/safes/{address}/export/:
    get:
      operationId: safes_export_retrieve
      description: 'Get transactions optimized for CSV export with transfer information.

        The maximum limit allowed is 1000.'
      parameters:
      - in: path
        name: address
        schema:
          type: string
        required: true
      - in: query
        name: execution_date__gte
        schema:
          type: string
          format: date-time
        description: Filter transactions executed after this date (ISO format)
      - in: query
        name: execution_date__lte
        schema:
          type: string
          format: date-time
        description: Filter transactions executed before this date (ISO format)
      - in: query
        name: limit
        schema:
          type: integer
        description: Maximum number of transactions to return (max 1000)
      - in: query
        name: offset
        schema:
          type: integer
        description: Number of transactions to skip
      tags:
      - safes
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSafeExportTransactionList'
          description: ''
        '404':
          description: Safe not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeErrorResponse'
          description: Safe address checksum not valid
      path: /tx-service/eth/api/v1/safes/{address}/export/
      title: Get Transactions for CSV Export
      additionalInfo: ''
  /tx-service/eth/api/v2/safes/{address}/balances/:
    get:
      operationId: safes_balances_retrieve_2
      description: 'Get paginated balances for Ether and ERC20 tokens.

        The maximum limit allowed is 200.'
      parameters:
      - in: path
        name: address
        schema:
          type: string
        required: true
      - in: query
        name: trusted
        schema:
          type: boolean
          default: false
        description: If `True` just trusted tokens will be returned
      - in: query
        name: exclude_spam
        schema:
          type: boolean
          default: false
        description: If `True` spam tokens will not be returned
      - in: query
        name: limit
        schema:
          type: integer
        description: Number of results to return per page.
      - in: query
        name: offset
        schema:
          type: integer
        description: The initial index from which to return the results.
      tags:
      - safes
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSafeCollectibleResponseList'
          description: ''
        '404':
          description: Safe not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeErrorResponse'
          description: Safe address checksum not valid
      path: /tx-service/eth/api/v2/safes/{address}/balances/
      title: Get Safe Balances
      additionalInfo: ''
  /tx-service/eth/api/v2/safes/{address}/collectibles/:
    get:
      operationId: safes_collectibles_retrieve
      description: 'Get paginated collectibles (ERC721 tokens) and information about them of a given Safe account.

        The maximum limit allowed is 10.'
      parameters:
      - in: path
        name: address
        schema:
          type: string
        required: true
      - in: query
        name: trusted
        schema:
          type: boolean
          default: false
        description: If `True` just trusted tokens will be returned
      - in: query
        name: exclude_spam
        schema:
          type: boolean
          default: false
        description: If `True` spam tokens will not be returned
      - in: query
        name: limit
        schema:
          type: integer
        description: Number of results to return per page.
      - in: query
        name: offset
        schema:
          type: integer
        description: The initial index from which to return the results.
      tags:
      - safes
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSafeCollectibleResponseList'
          description: ''
        '404':
          description: Safe not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeErrorResponse'
          description: Safe address checksum not valid
      path: /tx-service/eth/api/v2/safes/{address}/collectibles/
      title: List Collectibles
      additionalInfo: ''
components:
  schemas:
    PaginatedSafeCollectibleResponseList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/SafeCollectibleResponse'
    SafeCreationInfoResponse:
      type: object
      properties:
        created:
          type: string
          format: date-time
        creator:
          type: string
        transactionHash:
          type: string
        factoryAddress:
          type: string
        masterCopy:
          type:
          - string
          - 'null'
        setupData:
          type:
          - string
          - 'null'
        saltNonce:
          type:
          - string
          - 'null'
        dataDecoded:
          type: object
          additionalProperties: {}
          readOnly: true
        userOperation:
          oneOf:
          - $ref: '#/components/schemas/UserOperationWithSafeOperationResponse'
          - type: 'null'
      required:
      - created
      - creator
      - dataDecoded
      - factoryAddress
      - masterCopy
      - saltNonce
      - setupData
      - transactionHash
      - userOperation
    PaginatedSafeExportTransactionList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/SafeExportTransaction'
    CodeErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        arguments:
          type: array
          items: {}
      required:
      - arguments
      - code
      - message
    UserOperationWithSafeOperationResponse:
      type: object
      properties:
        ethereumTxHash:
          type: string
        sender:
          type: string
        userOperationHash:
          type: string
        nonce:
          type: string
        initCode:
          type:
          - string
          - 'null'
        callData:
          type:
          - string
          - 'null'
        callGasLimit:
          type: string
        verificationGasLimit:
          type: string
        preVerificationGas:
          type: string
        maxFeePerGas:
          type: string
        maxPriorityFeePerGas:
          type: string
        paymaster:
          type:
          - string
          - 'null'
        paymasterData:
          type:
          - string
          - 'null'
        signature:
          type: string
        entryPoint:
          type: string
        safeOperation:
          oneOf:
          - $ref: '#/components/schemas/SafeOperationResponse'
          - type: 'null'
          readOnly: true
      required:
      - callData
      - callGasLimit
      - entryPoint
      - ethereumTxHash
      - initCode
      - maxFeePerGas
      - maxPriorityFeePerGas
      - nonce
      - paymaster
      - paymasterData
      - preVerificationGas
      - safeOperation
      - sender
      - signature
      - userOperationHash
      - verificationGasLimit
    SafeExportTransaction:
      type: object
      description: Serializer for the export endpoint that returns transaction data optimized for CSV export
      properties:
        safe:
          type: string
        From:
          type: string
          title: ' from'
        to:
          type: string
        amount:
          type: string
        assetType:
          type: string
        assetAddress:
          type:
          - string
          - 'null'
        assetSymbol:
          type:
          - string
          - 'null'
        assetDecimals:
          type:
          - integer
          - 'null'
        proposerAddress:
          type:
          - string
          - 'null'
        proposedAt:
          type:
          - string
          - 'null'
          format: date-time
        executorAddress:
          type:
          - string
          - 'null'
        executedAt:
          type:
          - string
          - 'null'
          format: date-time
        note:
          type:
          - string
          - 'null'
        transactionHash:
          type: string
        contractAddress:
          type:
          - string
          - 'null'
        nonce:
          type:
          - string
          - 'null'
      required:
      - From
      - amount
      - assetAddress
      - assetDecimals
      - assetSymbol
      - assetType
      - contractAddress
      - executedAt
      - executorAddress
      - nonce
      - note
      - proposedAt
      - proposerAddress
      - safe
      - to
      - transactionHash
    SafeBalanceResponse:
      type: object
      properties:
        tokenAddress:
          type: string
        token:
          $ref: '#/components/schemas/Erc20Info'
        balance:
          type: string
      required:
      - balance
      - token
      - tokenAddress
    SafeCollectibleResponse:
      type: object
      properties:
        address:
          type: string
        tokenName:
          type: string
        tokenSymbol:
          type: string
        logoUri:
          type: string
        id:
          type: string
        uri:
          type: string
        name:
          type: string
        description:
          type: string
        imageUri:
          type: string
        metadata:
          type: object
          additionalProperties: {}
      required:
      - address
      - description
      - id
      - imageUri
      - logoUri
      - metadata
      - name
      - tokenName
      - tokenSymbol
      - uri
    Erc20Info:
      type: object
      properties:
        name:
          type: string
        symbol:
          type: string
        decimals:
          type: integer
        logoUri:
          type: string
      required:
      - decimals
      - logoUri
      - name
      - symbol
    SafeOperationResponse:
      type: object
      properties:
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        safeOperationHash:
          type: string
        validAfter:
          type: string
          format: date-time
        validUntil:
          type: string
          format: date-time
        moduleAddress:
          type: string
        confirmations:
          type: object
          additionalProperties: {}
          description: 'Filters confirmations queryset


            :param obj: SafeOperation instance

            :return: Serialized queryset'
          readOnly: true
        preparedSignature:
          type: string
          readOnly: true
      required:
      - confirmations
      - created
      - modified
      - moduleAddress
      - preparedSignature
      - safeOperationHash
      - validAfter
      - validUntil
    SafeInfoResponse:
      type: object
      properties:
        address:
          type: string
        nonce:
          type: string
        threshold:
          type: integer
        owners:
          type: array
          items:
            type: string
        masterCopy:
          type: string
        modules:
          type: array
          items:
            type: string
        fallbackHandler:
          type: string
        guard:
          type: string
        moduleGuard:
          type: string
        version:
          type:
          - string
          - 'null'
      required:
      - address
      - fallbackHandler
      - guard
      - masterCopy
      - moduleGuard
      - modules
      - nonce
      - owners
      - threshold
      - version
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token"