diff --git a/services/metadata/swagger.yaml b/services/metadata/swagger.yaml
new file mode 100644
index 0000000..a1a6a8c
--- /dev/null
+++ b/services/metadata/swagger.yaml
@@ -0,0 +1,341 @@
+swagger: "2.0"
+info:
+  title: v1/metadata.proto
+  version: version not set
+tags:
+  - name: Metadata
+  - name: Health
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  /api/v1/addresses:
+    get:
+      operationId: Metadata_GetPublicTagAddresses
+      responses:
+        "200":
+          description: A successful response.
+          schema:
+            $ref: '#/definitions/v1GetPublicTagAddressesResponse'
+        default:
+          description: An unexpected error response.
+          schema:
+            $ref: '#/definitions/rpcStatus'
+      parameters:
+        - name: slug
+          in: query
+          required: false
+          type: string
+        - name: tagType
+          in: query
+          required: false
+          type: string
+        - name: chainId
+          description: If not provided, only multichain tags will be returned
+          in: query
+          required: false
+          type: string
+          format: uint64
+        - name: pageSize
+          in: query
+          required: false
+          type: integer
+          format: int64
+        - name: pageToken
+          in: query
+          required: false
+          type: string
+      tags:
+        - Metadata
+  /api/v1/addresses:submit:
+    post:
+      operationId: Metadata_SubmitAddressesToExtractors
+      responses:
+        "200":
+          description: A successful response.
+          schema:
+            $ref: '#/definitions/v1SubmitAddressesToExtractorsResponse'
+        default:
+          description: An unexpected error response.
+          schema:
+            $ref: '#/definitions/rpcStatus'
+      parameters:
+        - name: body
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/v1SubmitAddressesToExtractorsRequest'
+      tags:
+        - Metadata
+  /api/v1/metadata:
+    get:
+      operationId: Metadata_BatchGetMetadata
+      responses:
+        "200":
+          description: A successful response.
+          schema:
+            $ref: '#/definitions/v1BatchGetMetadataResponse'
+        default:
+          description: An unexpected error response.
+          schema:
+            $ref: '#/definitions/rpcStatus'
+      parameters:
+        - name: addresses
+          description: Comma separated list of addresses
+          in: query
+          required: false
+          type: string
+        - name: chainId
+          description: If not provided, only multichain tags will be returned
+          in: query
+          required: false
+          type: string
+          format: uint64
+        - name: tagsLimit
+          description: If provided, the first `tags_limit` tags will be returned for each address
+          in: query
+          required: false
+          type: integer
+          format: int64
+        - name: tagTypes
+          description: Comma separated list of tag types
+          in: query
+          required: false
+          type: string
+      tags:
+        - Metadata
+  /api/v1/public-tag-types:
+    get:
+      operationId: Metadata_GetPublicTagTypes
+      responses:
+        "200":
+          description: A successful response.
+          schema:
+            $ref: '#/definitions/v1GetPublicTagTypesResponse'
+        default:
+          description: An unexpected error response.
+          schema:
+            $ref: '#/definitions/rpcStatus'
+      tags:
+        - Metadata
+  /api/v1/reputation:
+    get:
+      operationId: Metadata_BatchGetReputation
+      responses:
+        "200":
+          description: A successful response.
+          schema:
+            $ref: '#/definitions/v1BatchGetReputationResponse'
+        default:
+          description: An unexpected error response.
+          schema:
+            $ref: '#/definitions/rpcStatus'
+      parameters:
+        - name: addresses
+          description: Comma separated list of addresses
+          in: query
+          required: false
+          type: string
+      tags:
+        - Metadata
+  /api/v1/tags:search:
+    get:
+      operationId: Metadata_SearchPublicTags
+      responses:
+        "200":
+          description: A successful response.
+          schema:
+            $ref: '#/definitions/v1SearchPublicTagsResponse'
+        default:
+          description: An unexpected error response.
+          schema:
+            $ref: '#/definitions/rpcStatus'
+      parameters:
+        - name: chainId
+          in: query
+          required: false
+          type: string
+          format: uint64
+        - name: tagTypes
+          description: Comma separated list of tag types
+          in: query
+          required: false
+          type: string
+        - name: name
+          in: query
+          required: false
+          type: string
+        - name: pageSize
+          in: query
+          required: false
+          type: integer
+          format: int64
+        - name: pageToken
+          in: query
+          required: false
+          type: string
+      tags:
+        - Metadata
+  /health:
+    get:
+      summary: |-
+        If the requested service is unknown, the call will fail with status
+        NOT_FOUND.
+      operationId: Health_Check
+      responses:
+        "200":
+          description: A successful response.
+          schema:
+            $ref: '#/definitions/v1HealthCheckResponse'
+        default:
+          description: An unexpected error response.
+          schema:
+            $ref: '#/definitions/rpcStatus'
+      parameters:
+        - name: service
+          in: query
+          required: false
+          type: string
+      tags:
+        - Health
+definitions:
+  HealthCheckResponseServingStatus:
+    type: string
+    enum:
+      - UNKNOWN
+      - SERVING
+      - NOT_SERVING
+      - SERVICE_UNKNOWN
+    default: UNKNOWN
+    description: ' - SERVICE_UNKNOWN: Used only by the Watch method.'
+  protobufAny:
+    type: object
+    properties:
+      '@type':
+        type: string
+    additionalProperties: {}
+  rpcStatus:
+    type: object
+    properties:
+      code:
+        type: integer
+        format: int32
+      message:
+        type: string
+      details:
+        type: array
+        items:
+          type: object
+          $ref: '#/definitions/protobufAny'
+  v1AddressMetadataResponse:
+    type: object
+    properties:
+      tags:
+        type: array
+        items:
+          type: object
+          $ref: '#/definitions/v1Tag'
+  v1BatchGetMetadataResponse:
+    type: object
+    properties:
+      addresses:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/v1AddressMetadataResponse'
+  v1BatchGetReputationResponse:
+    type: object
+    properties:
+      addresses:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/v1Reputation'
+  v1GetPublicTagAddressesResponse:
+    type: object
+    properties:
+      addresses:
+        type: array
+        items:
+          type: string
+        title: 'TODO: remove this field'
+      items:
+        type: array
+        items:
+          type: string
+      nextPageParams:
+        $ref: '#/definitions/v1Pagination'
+  v1GetPublicTagTypesResponse:
+    type: object
+    properties:
+      tagTypes:
+        type: array
+        items:
+          type: object
+          $ref: '#/definitions/v1PublicTagType'
+  v1HealthCheckResponse:
+    type: object
+    properties:
+      status:
+        $ref: '#/definitions/HealthCheckResponseServingStatus'
+  v1Pagination:
+    type: object
+    properties:
+      pageToken:
+        type: string
+      pageSize:
+        type: integer
+        format: int64
+  v1PublicTagType:
+    type: object
+    properties:
+      id:
+        type: string
+      type:
+        type: string
+      description:
+        type: string
+  v1Reputation:
+    type: object
+    properties:
+      score:
+        type: integer
+        format: int32
+  v1SearchPublicTagsResponse:
+    type: object
+    properties:
+      tags:
+        type: array
+        items:
+          type: object
+          $ref: '#/definitions/v1Tag'
+        title: 'TODO: remove this field'
+      items:
+        type: array
+        items:
+          type: object
+          $ref: '#/definitions/v1Tag'
+      nextPageParams:
+        $ref: '#/definitions/v1Pagination'
+  v1SubmitAddressesToExtractorsRequest:
+    type: object
+    properties:
+      addresses:
+        type: array
+        items:
+          type: string
+  v1SubmitAddressesToExtractorsResponse:
+    type: object
+  v1Tag:
+    type: object
+    properties:
+      slug:
+        type: string
+      name:
+        type: string
+      tagType:
+        type: string
+      ordinal:
+        type: integer
+        format: int32
+      meta:
+        type: string