# Find an artist's X handle

Source: https://docs.musicnerd.net/api-reference/lookups/find-twitter-handle

Find an artist's X handle

## POST /api/findTwitterHandle

Full OpenAPI specification: https://docs.musicnerd.net/spec/artist-lookups.json

## Authentication

This operation's specification permits a request without authentication.

[Authentication guide](https://docs.musicnerd.net/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Music Nerd API: artist lookups",
    "version": "1.0.0",
    "description": "Find an artist by Spotify ID or Instagram handle, or an artist's X handle. No credentials."
  },
  "servers": [
    {
      "url": "https://musicnerd-api.vercel.app",
      "description": "Production"
    },
    {
      "url": "https://musicnerd-api-staging.vercel.app",
      "description": "Staging (staging database)"
    }
  ],
  "paths": {
    "/api/findTwitterHandle": {
      "post": {
        "summary": "Find an artist's X handle",
        "description": "Returns the X handle of an artist found by `ethAddress` or `name`. No credentials.\n\n`ethAddress` wins when both are sent. A `0x` address of 40 hex characters is matched exactly against the artist's wallets, then `ens`; any other value against `ens` only.\n\n`name` is a fuzzy search: substring matches first, then trigram similarity of at least 0.3. The best match is used.\n\n`result` is `null` when the artist has no X handle. A `name` that matches no artist returns 200 `{}`.\n\nResponses are `{ result }` with plain-text errors, not this API's `{ status }` envelope.",
        "operationId": "findTwitterHandle",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "ethAddress": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "ethAddress": "0x0000000000000000000000000000000000000001"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The artist's X handle, or `{}` when a name search matches nothing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                },
                "examples": {
                  "found": {
                    "value": {
                      "result": "exampleartist"
                    }
                  },
                  "noNameMatch": {
                    "value": {}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Neither `name` nor `ethAddress` is a non-empty string, or the body is not JSON.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "Missing or invalid required parameters: name or ethAddress"
              }
            }
          },
          "404": {
            "description": "`ethAddress` matches no wallet or ENS name.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "The artist you're searching for is not found"
              }
            }
          },
          "500": {
            "description": "The database could not be read.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "Something went wrong on our end"
              }
            }
          }
        }
      }
    }
  }
}
```