Safe (Gnosis Safe) delegates API

openapi: 3.1.0
info:
  title: Safe Transaction Service 4337 delegates API
  version: 6.3.0
  description: API to keep track of transactions sent via Safe smart contracts
tags:
- name: delegates
paths:
  /tx-service/eth/api/v1/delegates/:
    get:
      operationId: delegates_list
      description: Returns a list with all the delegates
      parameters:
      - in: query
        name: safe
        schema:
          type:
          - string
          - 'null'
      - in: query
        name: delegate
        schema:
          type: string
      - in: query
        name: delegator
        schema:
          type: string
      - in: query
        name: label
        schema:
          type: string
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - delegates
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      deprecated: true
      responses:
        '400':
          description: Invalid data
      path: /tx-service/eth/api/v1/delegates/
      title: List Delegates
      additionalInfo: ''
    post:
      operationId: delegates_create
      description: "Adds a new Safe delegate with a custom label. Calls with same delegate but different label or\nsigner will update the label or delegator if a different one is provided\nFor the signature we are using TOTP with `T0=0` and `Tx=3600`. TOTP is calculated by taking the\nUnix UTC epoch time (no milliseconds) and dividing by 3600 (natural division, no decimals)\nTo generate the signature, this hash needs to be signed: keccak(checksummed address + str(int(current_epoch //\n3600)))\nAs an example, if the 0x132512f995866CcE1b0092384A6118EDaF4508Ff delegate is added and epoch=1586779140:\n     - `TOTP = epoch // 3600 = 1586779140 // 3600 = 440771`\n     - keccak(\"0x132512f995866CcE1b0092384A6118EDaF4508Ff440771\") would be the hash a Safe owner would\n     need to sign.`"
      tags:
      - delegates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Delegate'
        required: true
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      deprecated: true
      responses:
        '202':
          description: Accepted
        '400':
          description: Malformed data
      path: /tx-service/eth/api/v1/delegates/
      title: Create Delegate
      additionalInfo: ''
  /tx-service/eth/api/v1/delegates/{delegate_address}/:
    delete:
      operationId: delegates_destroy
      description: 'Delete every pair delegate/delegator found. Signature is built the same way as for adding a delegate,

        but in this case the signer can be either the `delegator` (owner) or the `delegate` itself.

        Check `POST /delegates/`'
      parameters:
      - in: path
        name: delegate_address
        schema:
          type: string
        required: true
      tags:
      - delegates
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      deprecated: true
      responses:
        '204':
          description: Deleted
        '400':
          description: Malformed data
        '404':
          description: Delegate not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeErrorResponse'
          description: Invalid Ethereum address/Error processing data
      path: /tx-service/eth/api/v1/delegates/{delegate_address}/
      title: Delete Delegate
      additionalInfo: ''
  /tx-service/eth/api/v1/safes/{address}/delegates/{delegate_address}/:
    delete:
      operationId: safes_delegates_destroy
      description: 'Delete a delegate for a Safe. Signature is built the same way that for adding a delegate.

        Check `POST /delegates/`'
      parameters:
      - in: path
        name: address
        schema:
          type: string
        required: true
      - in: path
        name: delegate_address
        schema:
          type: string
        required: true
      tags:
      - delegates
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      deprecated: true
      responses:
        '204':
          description: Deleted
        '400':
          description: Malformed data
        '404':
          description: Delegate not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeErrorResponse'
          description: Invalid Ethereum address | Error processing data
      path: /tx-service/eth/api/v1/safes/{address}/delegates/{delegate_address}/
      title: Remove Delegate from Safe
      additionalInfo: ''
  /tx-service/eth/api/v2/delegates/:
    get:
      operationId: delegates_list_2
      description: Returns a list with all the delegates
      parameters:
      - in: query
        name: safe
        schema:
          type:
          - string
          - 'null'
      - in: query
        name: delegate
        schema:
          type: string
      - in: query
        name: delegator
        schema:
          type: string
      - in: query
        name: label
        schema:
          type: string
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - delegates
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSafeDelegateResponseList'
          description: ''
        '400':
          description: Invalid data
      path: /tx-service/eth/api/v2/delegates/
      title: List Delegates
      additionalInfo: ''
    post:
      operationId: delegates_create_2
      description: "Adds a new Safe delegate with a custom label. Calls with same delegate but different label or\nsigner will update the label or delegator if a different one is provided.\nTo generate the signature, the following EIP712 data hash needs to be signed:\n\n```python\n {\n    \"types\": {\n        \"EIP712Domain\": [\n            {\"name\": \"name\", \"type\": \"string\"},\n            {\"name\": \"version\", \"type\": \"string\"},\n            {\"name\": \"chainId\", \"type\": \"uint256\"},\n        ],\n        \"Delegate\": [\n            {\"name\": \"delegateAddress\", \"type\": \"address\"},\n            {\"name\": \"totp\", \"type\": \"uint256\"},\n        ],\n    },\n    \"primaryType\": \"Delegate\",\n    \"domain\": {\n        \"name\": \"Safe Transaction Service\",\n        \"version\": \"1.0\",\n        \"chainId\": chain_id,\n    },\n    \"message\": {\n        \"delegateAddress\": delegate_address,\n        \"totp\": totp,\n    },\n}\n```\n\nFor the signature we use `TOTP` with `T0=0` and `Tx=3600`. `TOTP` is calculated by taking the\nUnix UTC epoch time (no milliseconds) and dividing by 3600 (natural division, no decimals)."
      tags:
      - delegates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DelegateSerializerV2'
        required: true
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      responses:
        '202':
          description: Accepted
        '400':
          description: Malformed data
      path: /tx-service/eth/api/v2/delegates/
      title: Create Delegate
      additionalInfo: ''
  /tx-service/eth/api/v2/delegates/{delegate_address}/:
    delete:
      operationId: delegates_destroy_2
      description: 'Removes every delegate/delegator pair found associated with a given delegate address. The

        signature is built the same way as for adding a delegate, but in this case the signer can be

        either the `delegator` (owner) or the `delegate` itself. Check `POST /delegates/` to learn more.'
      parameters:
      - in: path
        name: delegate_address
        schema:
          type: string
        required: true
      tags:
      - delegates
      security:
      - cookieAuth: []
      - tokenAuth: []
      - {}
      responses:
        '204':
          description: Deleted
        '400':
          description: Malformed data
        '404':
          description: Delegate not found
        '422':
          description: Invalid Ethereum address/Error processing data
      path: /tx-service/eth/api/v2/delegates/{delegate_address}/
      title: Delete Delegate
      additionalInfo: ''
components:
  schemas:
    CodeErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        arguments:
          type: array
          items: {}
      required:
      - arguments
      - code
      - message
    DelegateSerializerV2:
      type: object
      description: Mixin to validate delegate operations data
      properties:
        safe:
          type:
          - string
          - 'null'
        delegate:
          type: string
        delegator:
          type: string
        signature:
          type: string
        label:
          type: string
          maxLength: 50
        expiryDate:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - delegate
      - delegator
      - label
      - signature
    PaginatedSafeDelegateResponseList:
      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/SafeDelegateResponse'
    SafeDelegateResponse:
      type: object
      properties:
        safe:
          type: string
        delegate:
          type: string
        delegator:
          type: string
        label:
          type: string
          maxLength: 50
        expiryDate:
          type: string
          format: date-time
      required:
      - delegate
      - delegator
      - expiryDate
      - label
      - safe
    Delegate:
      type: object
      description: ".. deprecated:: 4.38.0\n   Deprecated in favour of DelegateSerializerV2"
      properties:
        safe:
          type:
          - string
          - 'null'
        delegate:
          type: string
        delegator:
          type: string
        signature:
          type: string
        label:
          type: string
          maxLength: 50
      required:
      - delegate
      - delegator
      - label
      - signature
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token"