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
cipherowl.client.idcipherowl.client.secretcipherowl.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"
header
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)
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.