> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Entity by Name

> Resolve a canonical Shoal entity by canonical name or alias

This is the canonical entity lookup surface. Use it when you have a name like `Ethereum`, `Binance`, or `Tether` and need the stable Shoal entity id for traversal.

## Query Parameters

* `name` (string, required)
* `entityName` (string, optional) — Compatibility alias for `name`
* `limit` (integer, optional)
* `offset` (integer, optional)

## Request

```bash cURL theme={null}
curl -X GET "https://api.shoal.xyz/v1/entities/byName?name=Ethereum" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response (200)

```json theme={null}
{
  "data": [
    {
      "id": 23151,
      "canonicalName": "Ethereum",
      "displayName": "Ethereum",
      "entityType": "project",
      "status": "active",
      "aliases": ["Ethereum Foundation", "ETH"],
      "references": [],
      "matchedVia": "canonical_name",
      "matchType": "exact",
      "matchRank": 0,
      "matchedValue": "Ethereum"
    }
  ]
}
```

## Notes

* `id` is the stable Shoal traversal id for the entity.
* `references` is present in the canonical entity contract even before richer reference storage is populated.
* `matchedVia`, `matchType`, `matchRank`, and `matchedValue` explain why the entity matched the query.
* This route is the preferred canonical lookup surface going forward. `organizations/byOrganizationName` remains available as a compatibility route.

## Errors

* 400 if `name` is missing
* 500 on internal server error