Use GalliunClient.fetch() to call any protected API endpoint registered on the Galliun platform.

Basic POST request

const client = new GalliunClient({
  baseUrl: "https://api.galliun.com",
  chain: "sui",
  wallet: suiWallet,
});

const response = await client.fetch("/p/acme/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "best restaurants in Tokyo" }),
});

const data = await response.json();

GET requests

const response = await client.fetch("/p/acme/status", {
  method: "GET",
});

Dynamic path parameters

Some endpoints use path templates with {paramName} segments (for example /wallets/{address}/history). Galliun matches the resolved URL you call — the same values must be used for payment and execution.

Option 1 — resolved URL (manual):

const response = await client.fetch("/p/acme/wallets/0x123/history", {
  method: "GET",
});

Option 2 — template + params helper:

import { buildProtectedEndpointPath } from "galliun";

const path = buildProtectedEndpointPath("acme", "/wallets/{address}/history", {
  address: "0x123",
});

const response = await client.fetch(path, { method: "GET" });

The SDK does not compute the request hash — it uses the resolved path you pass to fetch(). Do not change path parameter values between the initial 402 response and the paid retry.

Directory listings expose pathTemplate, pathType, and public pathParams metadata so clients know which values to substitute.

JSON helper

const data = await client.fetchJson<{ results: string[] }>("/p/acme/search", {
  method: "POST",
  body: JSON.stringify({ query: "hello" }),
});

fetchJson throws APIError on non-OK responses with statusCode and responseBody.

Request body

• Pass a string body or a plain object (objects are JSON-stringified)
• The body must be identical on the 402 retry — the SDK handles this automatically
• Do not modify headers or body between initial call and retry

Response handling

Successful responses return a standard Response object. Many endpoints include payment metadata in the JSON body:

{
  "result": { "...": "..." },
  "payment": {
    "status": "captured",
    "chain": "sui",
    "asset": "USDC",
    "amount": "0.005",
    "txHashOrDigest": "..."
  },
  "cost": {
    "gross": "0.005",
    "platformFee": "0.0001",
    "providerNet": "0.0049"
  },
  "receiptId": "receipt_..."
}

See Receipts and Cost Breakdown.

Failure states

After payment succeeds but execution fails with a refund-recommended outcome, the response may include refundRecommendationId and refundRecommendationStatus: "recommended". Galliun does not issue refunds — see Refunds.

Common mistakes

• Wrong path — protected paths start with /p/{projectSlug}/
• Missing Content-Type — set "Content-Type": "application/json" for JSON bodies
• Ignoring 503 — unavailable endpoints never return 402; fix endpoint health first

Next steps

• Handling errors