Transport for the CipherOwl API: Bearer auth with re-mint on 401, path and query encoding, bodies that never send unset fields, input validation where CipherOwl's docs are explicit (chain names, EVM address format, hops, reference), HttpError with a readable message and the parsed Retry-After, and page-token pagination.

Addresses and risk results are wallet-risk data. Error messages from this package never include an address, a reference, or the body CipherOwl returned; the vendor's text is kept in HttpError.detail.

Per-call credentials. Every API-calling function has a trailing opts Map, resolved by resolve: opts first, then context, then defaults. Per-call credentials and minted tokens are masked in call records. A credential present but blank or null is an error, never a fallback to context. A per-call base-url needs a credential in the same opts: context credentials are never sent to a per-call URL.

Context Vars

Optional
  • cipherowl.client.id
  • cipherowl.client.secret
  • cipherowl.base.url

Values

CREDENTIAL_KEYS

CREDENTIAL_KEYS: Vec [
  "access-token",
  "client-id",
  "client-secret"
]

STATUS_HINTS

STATUS_HINTS: Map {
  "400": "bad request (check the chain, address, config and parameters)",
  "401": "the access token was rejected",
  "403": "not authorized (the path, or a config your plan cannot use)",
  "404": "not found (or owned by another organization)",
  "409": "conflict (the entry exists or its version changed)",
  "429": "rate limited",
  "500": "CipherOwl server error",
  "504": "timed out (re-check the result before retrying)"
}

Functions

build-request

fn (method: Str, path: Str, body: Any, token: Str, base-url: Str): ::hot::http/HttpRequest

The HttpRequest for one call: base-url + path, Authorization: Bearer, Accept: application/json, and a JSON body (nulls dropped) when body is not "". Exposed for testing.

Example

token ::cipherowl::auth/access-token({})
request ::cipherowl::api/build-request("GET", "/api/chain-capabilities/v1", "", token, ::cipherowl/BASE_URL)
request.url

call

fn (spec: Result): Any
fn (spec: Result, opts: Map): Any

Run a request spec {method, path, body?} (as the *-request builders return) through request. A spec that is an Err (a validation failure) is returned as is, without a request.

Example

spec ::cipherowl::cases/list-cases-request({excludeClosed: true, pageSize: 25})
page ::cipherowl::api/call(spec)
page.totalCount

check-addresses

fn (chain: Str, addresses: Vec): Vec

Validate every address for a chain (see validate-address): the trimmed addresses, or the first Err. Exposed for testing.

Example

::cipherowl::api/check-addresses("evm", [" 0x0000000000000000000000000000000000000001 "])  // ["0x0000000000000000000000000000000000000001"]
is-err(::cipherowl::api/check-addresses("evm", ["0x123"]))  // true

collect-pages

fn (fetch: Fn, key: Str, token: Str?, limit: Int, acc: Vec): Vec

Follow page tokens, concatenating each page's key Vec, until limit items, an empty page, or no nextPageToken. fetch takes the token (null for the first page) and returns one page. Exposed for testing; the list-all-* helpers use it.

Example

fetch (token) { if(is-null(token), {items: [1, 2], nextPageToken: "p2"}, {items: [3]}) }
::cipherowl::api/collect-pages(fetch, "items", null, 10, [])  // [1, 2, 3]
::cipherowl::api/collect-pages(fetch, "items", null, 2, [])  // [1, 2]

compact

fn (value: Any): Any

Drop null-valued keys, recursively through nested maps and vectors, so unset optionals are omitted. Exposed for testing.

Example

::cipherowl::api/compact({a: 1, b: null, c: {d: null}})  // {a: 1, c: {}}

error-detail

fn (body: Any): Str?

CipherOwl's own error text: body.message (or body.error) for JSON errors, the trimmed text for plain-text gateway errors, else null. Exposed for testing.

Example

::cipherowl::api/error-detail({message: "unsupported chain"})  // "unsupported chain"
::cipherowl::api/error-detail("  Bad Gateway  ")  // "Bad Gateway"

error-message

fn (status: Int, retry: Int?): Str

The readable message: status, its usual meaning and the retry delay. Never includes request data or the response body. Exposed for testing.

Example

::cipherowl::api/error-message(429, 30)  // "cipherowl: request failed with HTTP 429: rate limited; retry after 30s"
fn (headers: Any, name: Str): Str?

A header value by name, case-insensitively; null when absent. Exposed for testing.

Example

::cipherowl::api/header({"Retry-After": "30"}, "retry-after")  // "30"
::cipherowl::api/header({}, "retry-after")  // null

is-status

fn (e: Any, status: Int): Bool

True when e is a CipherOwl HttpError with this status (e.g. 404 for no override, 409 for a version conflict, 429 for rate limiting).

Example

::cipherowl::api/is-status({status: 404}, 404)  // true
::cipherowl::api/is-status({status: 429}, 404)  // false

next-page-token

fn (page: Any): Str?

The nextPageToken of a page, or null when it is absent or empty (no more pages). Exposed for testing.

Example

::cipherowl::api/next-page-token({nextPageToken: "abc"})  // "abc"
::cipherowl::api/next-page-token({nextPageToken: ""})  // null

normalize-band

fn (band: Any): Str?

A riskBand in plain words: "Severe Risk" → "severe", likewise low, medium, high. Null for a missing or unrecognized band (never guessed). Exposed for testing.

Example

::cipherowl::api/normalize-band("Severe Risk")  // "severe"
::cipherowl::api/normalize-band("Unknown")  // null

normalize-reference

fn (reference: Any): Str?

Normalize a screening reference the way CipherOwl does: trimmed and lowercased; empty means none (null). It must then be dot-separated segments of [a-z0-9_], at most 256 characters, e.g. acme.compliance.apac; anything else is an Err (CipherOwl would answer 400). Exposed for testing.

Example

::cipherowl::api/normalize-reference("Acme.Withdrawals")  // "acme.withdrawals"
::cipherowl::api/normalize-reference("  ")  // null
is-err(::cipherowl::api/normalize-reference("not valid"))  // true

number-or-null

fn (value: Any): Any

A finite number from an Int, a Dec, or a numeric Str (CipherOwl sends some numbers as strings); null for anything else, including the string "Infinity" that a directly flagged address reports. Never errs. Exposed for testing.

Example

::cipherowl::api/number-or-null("42.5")  // 42.5
::cipherowl::api/number-or-null("Infinity")  // null

query

fn (params: Map): Str

A ?a=1&b=2 suffix from the non-null entries of params (URL-encoded; booleans as true/false); "" when none are set.

Example

::cipherowl::api/query({hops: 2, config: null})  // "?hops=2"
::cipherowl::api/query({trackAlert: false})  // "?trackAlert=false"
::cipherowl::api/query({})  // ""

request

fn (method: Str, path: Str, body: Any): Any
fn (method: Str, path: Str, body: Any, opts: Map): Any

Make an authenticated CipherOwl request. path starts with /api/... and includes any query string; body is a Map (JSON, nulls dropped) or "" for none. Returns the decoded body on 2xx, or an Err carrying HttpError. The escape hatch for endpoints this package does not wrap. opts overrides credentials and settings for this call (see resolve).

Example

caps ::cipherowl::api/request("GET", "/api/chain-capabilities/v1", "")

resolve

fn (): Map
fn (opts: Map): Map

Resolve credentials and settings for one call: opts first, then context, then defaults. Returns {client-id, client-secret, access-token, base-url}, or an Err naming what is missing.

opts keys: access-token (a token you minted; used as is), client-id and client-secret (a pair; context credentials are then ignored for the call), and base-url (default ::cipherowl/BASE_URL; it needs a credential in the same opts). Credentials from opts are masked in call records and returned unchanged. A credential present but blank or null is an Err naming the key, never a fallback to context. Nothing is written to context except the minted-token cache (a secret, keyed by a hash of the credential identity), so tenants and parallel flows never share credentials.

Example

tenant {client-id: ::hot::ctx/get("tenant.client.id"), client-secret: ::hot::ctx/get("tenant.client.secret")}
::cipherowl::screening/screen-address("evm", "0x0000000000000000000000000000000000000001", {}, tenant)
Context Vars: cipherowl.client.id, cipherowl.client.secret, cipherowl.base.url

response-body

fn (body: Any): Any

Normalize a decoded 2xx body: empty text becomes null. Exposed for testing.

Example

::cipherowl::api/response-body("   ")  // null
::cipherowl::api/response-body({ok: true})  // {ok: true}

retry-after

fn (headers: Any): Int?

Parse Retry-After as whole seconds; null when absent or an HTTP date. Never errs. Exposed for testing.

Example

::cipherowl::api/retry-after({"retry-after": "30"})  // 30
::cipherowl::api/retry-after({"retry-after": "Wed, 21 Oct 2026 07:28:00 GMT"})  // null

seg

fn (value: Any): Str

Percent-encode one path segment (an address, network, pool id or case id).

Example

::cipherowl::api/seg("a/b")  // "a%2Fb"

send

fn (method: Str, path: Str, body: Any): ::hot::http/HttpResponse
fn (method: Str, path: Str, body: Any, opts: Map): ::hot::http/HttpResponse

Send an authenticated request and return the raw HttpResponse. A 401 on a minted token evicts it, mints a new one and retries once (as CipherOwl's client guide prescribes). 429s are not retried in-run (Hot has no sleep): the HttpError carries retry-after, so let a handler or schedule retry policy re-run the work. opts as for resolve.

Example

// The raw response, when you need its status or headers
response ::cipherowl::api/send("GET", "/api/chain-capabilities/v1", "")
response.status

// Prefer request unless you need that: it decodes the body and maps errors
::cipherowl::api/unwrap(response)

unwrap

fn (response: Result): Any

The decoded body of a 2xx response (null when empty), the Err of a failed transport, or err(HttpError) for a non-2xx response.

Example

HttpResponse ::hot::http/HttpResponse
::cipherowl::api/unwrap(HttpResponse({status: 200, headers: {}, body: {ok: true}}))  // {ok: true}
is-err(::cipherowl::api/unwrap(HttpResponse({status: 404, headers: {}, body: {message: "not found"}})))  // true

validate-address

fn (chain: Str, address: Str): Str

The address, trimmed, with its casing preserved (base58 is case-sensitive). On evm it must be 0x plus 40 hex characters (checksummed or lowercase), as documented; other chains are checked only for being non-empty and free of whitespace. The Err never includes the address. Exposed for testing.

Example

::cipherowl::api/validate-address("evm", "0x0000000000000000000000000000000000000001")  // "0x0000000000000000000000000000000000000001"
is-err(::cipherowl::api/validate-address("evm", "0x123"))  // true

validate-chain

fn (chain: Str): Str

The chain, trimmed and lowercased. Accepts a chain class from ::cipherowl/CHAINS (evm, bitcoin, tron, ...) or a specific chain from ::cipherowl::risk/chain-capabilities (ethereum, base, ...): screening and risk reasons take either and answer with the class, while reports need the class (see ::cipherowl::risk/chain-class). Errs when empty or not a lowercase identifier. Exposed for testing.

Example

::cipherowl::api/validate-chain(" EVM ")  // "evm"
is-err(::cipherowl::api/validate-chain(""))  // true

validate-hops

fn (hops: Any): Int?

hops when null or an Int from 0 to 8; otherwise an Err. Exposed for testing.

Example

::cipherowl::api/validate-hops(3)  // 3
is-err(::cipherowl::api/validate-hops(9))  // true

validate-network

fn (network: Str): Str

A network key (e.g. ethereum_mainnet, bitcoin_mainnet, tron_mainnet; aliases like ethereum resolve server-side), trimmed. Errs when empty or when given the chain family evm, which the docs say is not accepted. The live list is ::cipherowl::onchain/list-networks(). Exposed for testing.

Example

::cipherowl::api/validate-network("ethereum_mainnet")  // "ethereum_mainnet"
is-err(::cipherowl::api/validate-network("evm"))  // true

with-requested-chain

fn (body: Any, chain: Str): Any

A response body with requested-chain added: CipherOwl echoes the chain class (evm), not the chain you asked for (base), so this keeps the ask. Exposed for testing.

Example

::cipherowl::api/with-requested-chain({chain: "evm"}, "Base")  // {chain: "evm", requested-chain: "base"}

Types

HttpError

HttpError type {
    status: Int,
    headers: Map,
    body: Any,
    message: Str,
    detail: Str?,
    retry-after: Int?
}

A non-2xx CipherOwl response. status, headers and body as in the sibling packages; message is a readable summary (status and what it usually means) that never contains request data; detail is CipherOwl's own text (body.message for service errors, or the plain-text gateway body), which may echo the address you sent; retry-after is the parsed Retry-After in seconds (429), or null.