# General Relay Vessel Search API

> General Relay Vessel Search API is a paid API for AI agents from api.generalrelay.xyz, paid per call via x402, $0.02/call, status unknown (last checked 2026-09-15).

Search for vessels by identity (name, IMO, MMSI) and/or location (bounding box or radius), returning matching AIS vessel records.

## Facts

- Endpoint: GET https://api.generalrelay.xyz/v1/vessels
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/general-relay-vessel-search-api-544228bc
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_iQSAed7A6xjWR7MP1-Ev3

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability general-relay-vessel-search-api-544228bc
```

Example prompt: Can you find any vessels with 'PACIFIC' in their name that are currently near latitude 37.8 and longitude -122.4, within a 10-nautical-mile radius?

## When to prefer this

Use this endpoint when you need to search maritime vessel data by identity (name, IMO, MMSI) or by geographic area (bounding box up to 5°×5° or radius). Prefer it for agent workflows that need to resolve a vessel identifier to current position, or enumerate vessels in a specific maritime zone. Note that charges only apply on non-empty results, making it safe to probe.

## Known failure modes

- 400 Bad Request: invalid parameter values (e.g. lat/lon out of range, bounding box span exceeds 5°, malformed MMSI)
- 500 Internal Server Error: server-side failure, no charge applied
- 503 Service Unavailable: service temporarily down, no charge applied
- Empty array returned when no vessels match the filters — no charge applied
- Missing required query filter — must supply at least one of name, IMO, MMSI, or spatial parameters

## How this service works

Search vessels by identity, location, or both. Charged per non-empty result: empty array, 400, 500, 503 settle nothing.

## Output

An array of vessel records matching the query filters, each containing vessel identity fields (name, IMO, MMSI) and current or last-known position data (latitude, longitude). Returns an empty array if no matches are found. Charges apply only when the result array is non-empty.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [],
     "properties": {
      "imo": {
       "type": "integer",
       "description": "IMO number, exact match. A seven-digit international ship identifier. ANDs with name/mmsi/spatial filters."
      },
      "lat": {
       "type": "number",
       "description": "Center latitude in decimal degrees, for radius mode. Must be between -90 and 90."
      },
      "lon": {
       "type": "number",
       "description": "Center longitude in decimal degrees, for radius mode. Must be between -180 and 180."
      },
      "mmsi": {
       "type": "string",
       "pattern": "^[0-9]{9}$",
       "description": "The vessel's MMSI, exactly nine decimal digits, e.g. 366123456. Sent as text: leading zeros are significant. ANDs with other identity/spatial filters."
      },
      "name": {
       "type": "string",
       "description": "Vessel name, case-insensitive substring match. Leading and trailing whitespace is stripped. Example: name=PACIFIC matches \"PACIFIC ENDEAVOUR\". Combines with spatial and other identity filters."
      },
      "lat_max": {
       "type": "number",
       "description": "Northern latitude bound in decimal degrees, for bbox mode. Must be between -90 and 90, and greater than or equal to lat_min. The span (lat_max - lat_min) must not exceed 5°."
      },
      "lat_min": {
       "type": "number",
       "description": "Southern latitude bound in decimal degrees, for bbox mode. Must be between -90 and 90, and less than or equal to lat_max. The span (lat_max - lat_min) must not exceed 5°."
      },
      "lon_max": {
       "type": "number",
       "description": "Eastern longitude bound in decimal degrees, for bbox mode. Must be between -180 and 180, and greater than or equal to lon_min. The span (lon_max - lon_min) must not exceed 5°."
      },
      "lon_min": {
       "type": "number",
       "description": "Western longitude bound in decimal degrees, for bbox mode. Must be between -180 and 180, and less than or equal to lon_max. The span (lon_max - lon_min) must not exceed 5°."

… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/general-relay-vessel-search-api-544228bc/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.generalrelay.xyz](https://www.zero.xyz/host/api.generalrelay.xyz/llms.txt)