Skip to main content
GET
/
v1
/
entities
/
byName
Get Entity by Name
curl --request GET \
  --url https://api.shoal.xyz/v1/entities/byName \
  --header 'Authorization: Bearer <token>'
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

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

​
Response (200)

{
  "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