Look up vessels in the US Coast Guard PSIX registry by name (partial match), call sign, official number, hull number (HIN), flag country, service type, or build year. Returns matching vessels with the USCG vessel id, name, call sign, service type, build year, status, official number, HIN, and flag. Keyless, public-domain. Covers US-flagged vessels (and foreign vessels with US port-state-control activity). Pair the returned vesselId with maritime.cases for the inspection record. (Cross-references trade.locode for ports.)
/api/maritime/vesselPAYMENT-SIGNATURE.The vessel API is a pay-per-call maritime endpoint built for AI agents and autonomous software. Look up vessels in the US Coast Guard PSIX registry by name (partial match), call sign, official number, hull number (HIN), flag country, service type, or build year.
There is no signup and no API key. An agent (or any HTTP client) hits the endpoint, receives an x402 "402 Payment Required" challenge, signs a sub-cent USDC payment on Base or Solana, and retries — the data comes back on the paid request. That makes it a drop-in vessel data source for an agent tool-use loop, an MCP host, or a backend that needs maritime data on demand without onboarding to yet another vendor portal.
| Name | Type | Description |
|---|---|---|
name | string | max 100 chars |
callSign | string | max 40 chars |
officialNumber | string | max 40 chars |
hullNumber | string | max 40 chars |
flag | string | max 60 chars |
service | string | max 60 chars |
buildYear | string | match ^\d{4}$ |
vesselId | string | match ^\d+$ |
# 1. Probe with no auth → 402 envelope with PaymentRequirements curl -sS 'https://2s.io/api/maritime/vessel?name=example&callSign=example&officialNumber=example&hullNumber=example&flag=example&service=example&buildYear=12345&vesselId=12345' # 2. Sign + retry with PAYMENT-SIGNATURE: curl -sS 'https://2s.io/api/maritime/vessel?name=example&callSign=example&officialNumber=example&hullNumber=example&flag=example&service=example&buildYear=12345&vesselId=12345' \ -H 'PAYMENT-SIGNATURE: <base64-json-payload>' # Or use the canonical runner (handles probe → sign → retry): # EVM_PRIVATE_KEY=0x... node --env-file=.env.local \ # --experimental-strip-types scripts/x402-pay.ts \ # 'https://2s.io/api/maritime/vessel?name=example&callSign=example&officialNumber=example&hullNumber=example&flag=example&service=example&buildYear=12345&vesselId=12345'
import { TwoS } from '@2sio/sdk'
const client = new TwoS({
privateKey: process.env.EVM_PRIVATE_KEY as `0x${string}`,
})
const result = await client.maritime.vessel({
"name": "example",
"callSign": "example",
"officialNumber": "example",
"hullNumber": "example",
"flag": "example",
"service": "example",
"buildYear": "12345",
"vesselId": "12345"
})
console.log('endpoint:', result.endpoint)
console.log('cost:', result.costUsd, 'USDC')
console.log('tx:', result.settlement?.txHash)
console.log('data:', result.data)import os
from twosio import TwoS
client = TwoS(private_key=os.environ["EVM_PRIVATE_KEY"])
result = client.maritime.vessel(name="example", callSign="example", officialNumber="example", hullNumber="example", flag="example", service="example", buildYear="12345", vesselId="12345")
print("endpoint:", result.endpoint)
print("cost:", result.cost_usd, "USDC")
print("tx:", (result.settlement or {}).get("tx_hash"))
print("data:", result.data)// 1. Add @2sio/mcp to your MCP host config (Claude Desktop example below).
// EVM_PRIVATE_KEY funds x402 payments per call.
// claude_desktop_config.json
{
"mcpServers": {
"2sio": {
"command": "npx",
"args": ["-y", "@2sio/mcp"],
"env": { "EVM_PRIVATE_KEY": "0x..." }
}
}
}
// 2. Once the server is running, agents call this tool via standard MCP:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "maritime.vessel",
"arguments": {
"name": "example",
"callSign": "example",
"officialNumber": "example",
"hullNumber": "example",
"flag": "example",
"service": "example",
"buildYear": "12345",
"vesselId": "12345"
}
}
}| Field | Type | Description |
|---|---|---|
ok | boolean | one of: true |
items | array | |
total | integer | Total matching rows upstream; null when unknown. |
source | object |
{
"ok": true,
"items": [
{
"vesselId": 1,
"name": "example",
"callSign": "example",
"serviceType": "example",
"buildYear": 1,
"status": "example",
"officialNumber": "example",
"hullNumber": "example",
"flag": "example"
}
],
"total": 1,
"source": {
"provider": "example",
"url": "example",
"license": "example"
}
}