API Reference

Portal relay exposes one control-plane API. Frontends, SDK clients, peer relays, and operators all talk to this API, but each group has a small owned surface. Local agent endpoints under /agent/* are not part of the relay API.

JSON Envelope

Matched JSON control endpoints return this envelope:

{
  "ok": true,
  "data": {}
}

Error responses use the same envelope with error instead of data:

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "unauthorized"
  }
}

data is omitted on error. error is omitted on success.

The envelope does not apply to streaming or delegated endpoints:

Unknown routes may be handled by the frontend fallback or return a normal HTTP 404 outside the envelope.

Auth Schemes

The QUIC datagram backhaul carries the lease access token in a JSON message on its first stream, rather than an HTTP header. Cache endpoints can return plain-text HTTP errors for unsupported methods or exhausted request slots.

Admin auth and SDK lease auth issue different tokens and are not interchangeable. SDK lease registration uses SIWE; relay admin access uses the configured admin token.

Endpoint Groups

Public

Detailed contracts: SDK API and Admin and Policy API.

SDK

Admin

/admin itself is a frontend route, not a relay API endpoint.

Payments

Relay /api/x402/* endpoints are optional relay-owned control-plane facilitator endpoints. Enable them with X402_ENABLED=true when a relay operator wants to reserve support for relay resources such as future tunnel registration fees, lease renewal fees, raw TCP/UDP port allocation, or premium capacity. They are served by the embedded gosuda/x402-facilitator handler and do not use the Portal JSON envelope. Portal selects Sui mainnet by default and Sui testnet when X402_TESTNET=true. Portal accepts only USDC gasless stablecoin address-balance payments. X402_PAY_TO is the relay-owned payment recipient.

Relay x402 settings do not affect tunnel paid routes. Tunnel payment recipients and payment networks are local tunnel configuration and are not part of the relay lease API.

Paid routed HTTP tunnels additionally expose /x402/prepare and /x402/client.js on the public tunnel origin. Those are tunnel-owned helper endpoints for app frontends, not relay API routes, and they do not use the /api prefix. /x402/client.js and the transaction-building prepare response are Sui-only. Casper clients consume the protected resource’s 402 requirements, sign with an external Casper x402 SDK, and retry with PAYMENT-SIGNATURE or X-PAYMENT; Portal then delegates verification and settlement to the configured Casper facilitator.

Policy

Relay

Shared Types

Timestamps are JSON-encoded Go time.Time values.

Identity:

LeaseMetadata:

Lease:

PolicyLease extends Lease with:

PublicStateResponse:

PolicyStateResponse:

PolicyPortSettings:

PolicySettings:

LeasePolicyUpdate:

DiscoveryResponse:

release_version and relay_release_versions are optional, unsigned observation metadata: they never affect routing, trust, signature verification, or compatibility, and older relays omit them. Signed relay identity stays in RelayDescriptor.

Common Errors