URnetwork
•••
Operator API

URnetwork

Version 2026.1.6 · 128 operations across 14 groups.OpenAPI spec ↗

URnetwork implements the UR protocol operator spec in full. UR protocol ↗

URnetwork is a web-standards VPN marketplace with an emphasis on fast, secure internet everwhere.

The API for URnetwork bootstraps the connect protocol, and is the source of JWTs and other match-making transactions.

The JWT returned by /auth routes does not have a clientId. The connect protocol requires a JWT with a clientId. Use the /network routes to obtain a JWT with a clientId.

In URnetwork:

  • a network name is a globally unique subnet (xyz.ur.network)
  • a clientId is a globally unique 16-byte address
  • clientIds are equivalent to IPv6, but are expressed as UDID
  • clients also have an IPv6 and IPv4 mapped to their clientId

Outside of IP translation like taptun/utun, clients are typically addressed via their clientId.

Unless otherwise specified, time/date strings will be formatted in the Go default 2006-01-02 15:04:05.999999999 -0700 MST (RFC 3339).

Responses may include additional fields beyond those documented here. Clients should ignore unknown fields (be liberal in what you accept).

Authentication

20 operations
POST/auth/loginPublicAuth Login

Start a login for a user authority. The user authority may be:

  • email
  • phone number
  • Apple JWT
  • Google JWT
  • a wallet (wallet_auth): a Solana or Bittensor signature over the single-use challenge from /auth/wallet-challenge. A bound wallet returns network.by_jwt; an unbound wallet echoes wallet_auth and the client continues to /auth/network-create with a fresh challenge.
  • a seedphrase
Request bodyshow schema
user_auth
string

email or phone number

auth_jwt
string
auth_jwt_type
string
enum: apple, google
wallet_auth
WalletAuthArgs
wallet_address
string

Solana base58 public key, or Bittensor ss58 address (prefix 42, checksum verified)

wallet_message
string

The message_template issued by /auth/wallet-challenge, unmodified (no wrapper, LF line endings)

wallet_signature
string

Solana: base64 ed25519 signature over the message. Bittensor: hex of the 64-byte sr25519 signature (with or without 0x) made in the substrate signing context, over the raw or -wrapped message

blockchain
string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor
Responses1 status · show schema
200
user_name
string
user_auth
string

email or phone number

auth_allowed
array<string>

The sign-in methods on file for this user authority

array
string
enum: password, email, phone, apple, google, solana, bittensor, seedphrase
error
object
suggested_user_auth
string
enum: password, apple, google
message
string
network
object
by_jwt
string
wallet_auth
WalletAuthArgs
wallet_address
string

Solana base58 public key, or Bittensor ss58 address (prefix 42, checksum verified)

wallet_message
string

The message_template issued by /auth/wallet-challenge, unmodified (no wrapper, LF line endings)

wallet_signature
string

Solana: base64 ed25519 signature over the message. Bittensor: hex of the 64-byte sr25519 signature (with or without 0x) made in the substrate signing context, over the raw or -wrapped message

blockchain
string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor
POST/auth/wallet-challengePublicAuth Wallet Challenge

Issue a single-use wallet sign-in challenge. The wallet signs the returned message_template byte for byte; the signature is then submitted as wallet_auth to /auth/login, /auth/network-create or /auth/add-auth, each of which consumes one challenge. The message is exactly three LF-separated lines: Sign in to URnetwork, Challenge: and Timestamp: ; the server rejects any other text (400 invalid message format), a challenge that is unknown, expired (5 minutes), already used, issued for another blockchain or address, or whose timestamp differs from the issued one. Bittensor (TAO) wallets sign with sr25519 in the substrate context; both the raw text and the polkadot-js …-wrapped form of the signature verify, and the unwrapped text is what the client submits. Rate limited per client address. See server/BITTENSOR-LOGIN.md.

Request bodyshow schema
blockchain
string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor
wallet_address
string

Optional. Solana base58 public key or Bittensor ss58 address; when given, the challenge is bound to it.

Responses1 status · show schema
200
challenge
string

32 random bytes, base64url; embedded in message_template

timestamp
integer

unix seconds the challenge was issued; embedded in message_template

expires_in
integer

seconds until the challenge expires (300)

message_template
string

The exact text to sign: Sign in to URnetwork Challenge: Timestamp:

error
object
message
string
POST/auth/login-with-passwordPublicAuth Login With Password

Password login for email and phone number.

Request bodyshow schema
user_auth
string

email or phone number

password
string
verify_otp_numeric
boolean
Responses1 status · show schema
200
verification_required
object
user_auth
string

email or phone number

network
object
by_jwt
string
name
string
error
object
message
string
POST/auth/verifyPublicAuth Verify

Verify ownership of email or phone number.

Request bodyshow schema
user_auth
string

email or phone number

verify_code
string
Responses1 status · show schema
200
network
object
by_jwt
string
error
object
message
string
GET/auth/refreshBearer authAuth Refresh Token

Refresh the client JWT (by_jwt) for the caller's client. Requires a client JWT (from /network/auth-client).

Responses1 status · show schema
200
by_jwt
string

The refreshed client JWT.

error
object
message
string
POST/auth/verify-sendPublicAuth Verify Send

Send verification code to email or phone number.

Request bodyshow schema
user_auth
string

email or phone number

use_numeric
boolean

optionally create a numeric 6 digit code instead of the default 8 digit

Responses1 status · show schema
200
user_auth
string

email or phone number

POST/auth/password-resetPublicAuth Password Reset

Send password reset code to email or phone number.

Request bodyshow schema
user_auth
string

email or phone number

Responses1 status · show schema
200
user_auth
string

email or phone number

POST/auth/password-setPublicAuth Password Set

Change password.

Request bodyshow schema
reset_code
string
password
string
Responses1 status · show schema
200
empty object
POST/auth/network-checkPublicAuth Network Check

Check if the network name is available. A new network name must satisfy:

  • at least 3 characters different from an existing network name
  • at least 8 characters
  • domain name compatible (see RFC 5890)
  • not contain the dash (-) character (URnetwork subdomains are reverse-flattened to a single level using dashes)
Request bodyshow schema
network_name
string
Responses1 status · show schema
200
available
boolean
POST/auth/network-createPublicauthNetworkCreate

Create a new network. A user authority can be associated with at most one network.

Request bodyshow schema
user_name
string
user_auth
string

email or phone number

auth_jwt
string
auth_jwt_type
string
enum: apple, google
password
string
network_name
string
terms
boolean

user consent to accept terms of service

verify_use_numeric
boolean
wallet_auth
WalletAuthArgs
wallet_address
string

Solana base58 public key, or Bittensor ss58 address (prefix 42, checksum verified)

wallet_message
string

The message_template issued by /auth/wallet-challenge, unmodified (no wrapper, LF line endings)

wallet_signature
string

Solana: base64 ed25519 signature over the message. Bittensor: hex of the 64-byte sr25519 signature (with or without 0x) made in the substrate signing context, over the raw or -wrapped message

blockchain
string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor
referral_code
string

Optional referral code of the network that referred this new network.

balance_code
string

Optional balance code to add transfer balance to the new network.

product_updates
boolean

The sign-up form's "Periodic product updates" line. Absent = true (the line ships ticked). false turns the product-updates preference off from the first moment: no onboarding campaign mail is ever sent. Honored on every create path, including sign-ups that complete through /auth/verify. The server records a signup.optout_changed event with the value.

Responses2 statuses · show schema
200
network
object
by_jwt
string
network_id
string

uuid

network_name
string
is_pro
boolean
user_auth
string

email or phone number

is_pro
boolean
verification_required
object
user_auth
string

email or phone number

error
object
message
string
400
No body
POST/auth/network-deleteBearer authAuth Network Delete

Delete network

Responses1 status · show schema
200
error
object
message
string
POST/auth/code-createBearer authAuth Code Create

Create a limited use code (auth code) to share authentication with connected apps and tools. The code is tied to the caller session, and will be expired with any of the caller's sessions. Currently a code cannot be created for a client JWT (from /network/auth-client). This is a subset of an OAuth flow.

Request bodyshow schema
duration_minutes
number
uses
integer
roles
array<string>

Optional. Identity roles carried by logins minted from this code. Only a network session may set these. The values have no meaning to the network.

array
string
principal
string

Optional. Identity principal carried by logins minted from this code. Only a network session may set this.

Responses1 status · show schema
200
auth_code
string
duration_minutes
number
uses
integer
error
object
auth_code_limit_exceeded
boolean
message
string
GET/auth/apple/callbackBearer auth
Parameters
state(query)
string
required
id_token(query)
string
code(query)
string
user(query)
string
error(query)
string
Responses2 statuses · show schema
302
No body
400
No body
POST/auth/apple/callbackBearer auth

Apple has no SDK for android, windows or linux, so those apps open Apple's authorize page in the system browser (a Custom Tab on android) with client_id = the Apple Services ID, redirect_uri = this endpoint, response_type=code id_token, response_mode=form_post, scope=name email, and a fresh state and nonce per attempt. Apple posts the result here as a form, and this endpoint answers 302 to the app's own scheme so the browser hands control back to the app:

://oauth/apple?state=…&id_token=…&code=…&user=… ://oauth/apple?state=…&error=…

user is the JSON name/email Apple sends with the first authorization only. Nothing is stored or verified here: the app checks that state is the attempt it started and that the identity token's nonce claim is the one it minted, then signs in with the token through POST /auth/login (auth_jwt_type: apple), which verifies the signature and the audience.

state is opaque except for one optional claim: when it is the base64url encoding of a JSON object with a platform key, that key picks the scheme (android → ur://, windows and linux → urnetwork://); without it the android scheme is used. GET with the same parameters as a query behaves the same way (manual testing).

Request bodyshow schema
state
string

The attempt's state, echoed by Apple untouched.

code
string

Apple's authorization code (unused by the apps, passed through).

id_token
string

Apple's identity token (a JWT carrying the attempt's nonce).

user
string

JSON with the user's name and email, first authorization only.

error
string

Apple's error, e.g. user_cancelled_authorize.

Responses2 statuses · show schema
302
No body
400
No body
GET/auth/google/callbackBearer auth

Windows and Linux have no native Google sign-in, so those apps open Google's authorize page in the system browser with client_id = the ur.io web sign-in client, redirect_uri = this endpoint, response_type=code, scope=openid email profile, prompt=select_account, and a fresh state and nonce per attempt (android signs in with play services and ur.io in the page; neither uses this). Google redirects the browser here with the authorization code; this endpoint exchanges it at Google's token endpoint with the web client's secret (vault google.yml sign_in_oauth) and answers 302 to the app's own scheme so the browser hands control back to the app:

://oauth/google?state=…&id_token=… ://oauth/google?state=…&error=…

Nothing is stored. The app checks that state is the attempt it started and that the identity token's nonce claim is the one it minted, then signs in with the token through POST /auth/login (auth_jwt_type: google), which verifies the signature and the audience.

state is opaque except for the optional platform claim shared with the Apple callback: base64url JSON with a platform key picks the scheme (android → ur://, windows and linux → urnetwork://); without it the android scheme is used. Google's own error (e.g. access_denied) is passed through; a failed exchange or a missing client configuration comes back as error too (not_configured when the vault has no sign_in_oauth).

Parameters
state(query)
string

The attempt's state, echoed by Google untouched.

required
code(query)
string

Google's authorization code, exchanged here for the identity token.

error(query)
string

Google's error, e.g. access_denied.

Responses3 statuses · show schema
302
No body
400
No body
405
No body
POST/auth/code-loginPublicAuth Code Login

Authenticate with an auth code. The returned session is tied to the session that created the auth code, and will be expired with any of the creator's sessions. This is a subset of an OAuth flow.

Request bodyshow schema
auth_code
string
Responses1 status · show schema
200
by_jwt
string
error
object
message
string
POST/auth/add-authBearer authAuth Add Auth

Add an authentication method (email/phone + password, SSO, or wallet) to the calling user. A wallet (wallet_auth, Solana or Bittensor) must sign the single-use challenge from /auth/wallet-challenge, the same proof as wallet login; one wallet address binds to one user. Subject to the account action rate limit.

Request bodyshow schema
user_auth
string

email or phone number

auth_jwt
string
auth_jwt_type
string
enum: apple, google
password
string
wallet_auth
WalletAuthArgs
wallet_address
string

Solana base58 public key, or Bittensor ss58 address (prefix 42, checksum verified)

wallet_message
string

The message_template issued by /auth/wallet-challenge, unmodified (no wrapper, LF line endings)

wallet_signature
string

Solana: base64 ed25519 signature over the message. Bittensor: hex of the 64-byte sr25519 signature (with or without 0x) made in the substrate signing context, over the raw or -wrapped message

blockchain
string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor
Responses1 status · show schema
200
error
object
message
string
POST/auth/remove-authBearer authAuth Remove Auth

Remove an authentication method from the calling user. The last remaining method cannot be removed.

Request bodyshow schema
auth_type
string

The sign-in method to remove; the last remaining method cannot be removed

enum: email, phone, apple, google, solana, bittensor, seedphrase
Responses1 status · show schema
200
error
object
message
string
POST/auth/generate-seedphraseBearer authAuth Generate Seedphrase

Generate a recovery seedphrase for the calling user. Fails if a seedphrase auth already exists; see /auth/regenerate-seedphrase.

Responses1 status · show schema
200
seedphrase
string
error
object
message
string
POST/auth/regenerate-seedphraseBearer authAuth Regenerate Seedphrase

Replace the calling user's recovery seedphrase with a new one, invalidating the previous seedphrase.

Responses1 status · show schema
200
seedphrase
string
error
object
message
string

Network

18 operations
POST/network/auth-clientBearer authauthNetworkClient

Gain permission to use the connect protocol as the requested clientId, or assign a new clientId. Each network can have at most 128 clientIds. Above that number, new clientId requests will error until one or more existing clientIds are removed.

Request bodyshow schema
client_id
string

udid. Optional. If this is given, it must currently exist in the network. Omit this to assign a new client id.

source_client_id
string

udid. Optional. The source client id when creating an ancillary client id.

description
string

If this is a new device, sets the device name to the description of the device.

device_spec
string

If this is a new device, sets the device spec.

time_zone
string

Optional. The device's IANA time zone (e.g. America/Chicago), used only to place the onboarding campaign's emails in the user's local day (08:00-21:00 local); never stored on the client. Every app sends it on each auth-client call; the latest wins.

locale
string

Optional. The device's BCP 47 locale ("de-DE"). Selects the onboarding campaign's template language, falling back to English. Same rules as time_zone.

roles
array<string>

Optional. Identity roles assigned to the client at creation, immutable after. Only a network session may set these; when omitted, the session's own roles are inherited. The values have no meaning to the network.

array
string
principal
string

Optional. Identity principal assigned to the client at creation, immutable after. Only a network session may set this; when omitted, the session's own principal is inherited.

proxy_config
object

Optional. Set if the intended use case of the client is cloud proxy. Note local traffic is not allowed on the cloud proxy. A destination must be set via the SDK.

lock_caller_ip
boolean

Optional. Allow only the caller's IP subnet to access the proxy.

lock_ip_list
array<string>

Optional. Allow only IPs/subnets in the list to access the proxy. The IPs/subnets are converted to the internal IP subnet width.

array
string
https_require_auth
boolean

Optional. If the client supports ECH, this is not needed, since the HTTP proxy URL will itself be the auth.

enable_wg
boolean

Optional. If enabled, a WireGuard configuration will be created for the proxy.

initial_device_state
object

Optional. Whenever the device is created, it will be set up with this initial state. To configure the device beyond the initial state, the SDK ProxyDevice must be used. Note that the SDK ProxyDevice must reconfigure the device each time it receives a change notice.

country_code
string

Optional. Use one of country_code or location

location
object

Optional. Use one of country_code or location

connect_location_id
object
client_id
string

udid. Optional.

location_id
string

udid. Optional.

location_group_id
string

udid. Optional.

best_available
boolean

udid. Optional.

name
string
location_type
one of
one of
value
value
value
performance_profile
object
window_type
one of

Optional. The default is "quality"

one of
value
value
window_size
object
window_size_min
integer
window_size_min_p2p_only
integer

The minimumum number of items in the windows that must be connected via p2p only. Leave 0 for default behavior.

window_size_max
integer

Inclusive, soft limit. When window_size_max==window_size_min, a special fixed size mode is enabled.

window_size_hard_max
integer

Leave 0 to disable (no hard limit)

window_size_reconnect_scale
number

Clients per source per stream

keep_healthiest_count
integer

Leave 0 to disable

ulimit
integer

Leave 0 to disable (no limit)

Responses2 statuses · show schema
200
by_client_jwt
string
client_id
string

udid

proxy_config_result
all of

The following proxy URLs and auths may be used:

URLAuth
https://.:no auth needed when the client connects with TLS
https://:use HTTP Proxy-Authorization Basic with access_token as the username (empty pass), or Bearer with access_token as the bearer token
http://:use HTTP Proxy-Authorization Basic with access_token as the username (empty pass), or Bearer with access_token as the bearer token
tcp://:use access_token as the username (empty pass)
wg://:use wg_config.config as the full WireGuard config file content, which contains all the necessary keys
keepalive_seconds
integer

The proxy url will be valid until the client is removed. However, to keep the device and state in memory, the proxy must receive a message at least once per this interval. The SDK ProxyDevice will automatically send a heartbeat with this many seconds. If the proxy is removed from memmory, the next call to the proxy will create a new device set up to the initial_device_state (if present).

change_id
integer
create_time
string

datetime

proxy_id
string

udid

client_id
string

udid

api_base_url
string
block
string
api_port
integer
http_proxy_url
string
https_proxy_url
string
socks_proxy_url
string
auth_token
string
instance_id
string

udid. The instance_id of the proxy device.

proxy_host
string
socks_proxy_port
integer
http_proxy_port
integer
https_proxy_port
integer
wg_config
object
wg_proxy_port
integer
client_private_key
string
client_public_key
string
client_ipv4
string
proxy_public_key
string
config
string

The WireGuard config file for this client.

error
object
client_limit_exceeded
boolean
message
string
401
No body
POST/network/remove-clientBearer authRemove Network Client

Remove a client from the network.

Request bodyshow schema
client_id
string

udid

Responses1 status · show schema
200
error
object
message
string
GET/network/clientsBearer authNetwork Clients

Get the latest status of the network's devices: every top-level client (no sourceclientid) that is not a hosted proxy device, with no provide-mode qualification. Child clients are never listed, and neither are the network's cloud proxy devices (the "resident proxy" clients the proxy host runs), which /network/proxies lists instead.

Includes:

  • Resident status, which is the platform counterpart

for the client that handles control commands.

  • Connections, which are transports from the client to the platform.

Note there can be multiple active connections for a single client.

  • Provide status

proxy_client is never present on this list.

Responses1 status · show schema
200
clients
array<object>
array
client_id
string

udid

source_client_id
string

udid

device_id
string

udid

network_id
string

udid

description
string
device_name
string
device_spec
string
create_time
string
auth_time
string
roles
array<string>

identity roles assigned at creation

array
string
principal
string

identity principal assigned at creation

provide_mode
ProvideMode
one of
value
value
value
value
value
value
proxy_client
ProxyClient
change_id
integer
create_time
string

datetime

proxy_id
string

udid

client_id
string

udid

api_base_url
string
block
string
api_port
integer
http_proxy_url
string
https_proxy_url
string
socks_proxy_url
string
auth_token
string
instance_id
string

udid. The instance_id of the proxy device.

proxy_host
string
socks_proxy_port
integer
http_proxy_port
integer
https_proxy_port
integer
wg_config
object
wg_proxy_port
integer
client_private_key
string
client_public_key
string
client_ipv4
string
proxy_public_key
string
config
string

The WireGuard config file for this client.

resident
object
client_id
string

udid

instance_id
string

udid

resident_id
string

udid

resident_host
string
resident_service
string
resident_block
string
resident_internal_ports
array<integer>
array
integer
connections
array<object>
array
client_id
string

udid

connection_id
string

udid

connect_time
string
disconnect_time
string
connection_host
string
connection_service
string
connection_block
string'
GET/network/proxiesBearer authNetwork Proxies

The network's cloud proxy devices: the clients that carry a hosted proxy device (created with proxy_config on /network/auth-client), each with its proxy_client credentials (proxy URLs, auth token, WireGuard details). Same row shape as /network/clients otherwise: resident status, connections, provide status.

Responses1 status · show schema
200
clients
array<object>
array
client_id
string

udid

source_client_id
string

udid

device_id
string

udid

network_id
string

udid

description
string
device_name
string
device_spec
string
create_time
string
auth_time
string
roles
array<string>

identity roles assigned at creation

array
string
principal
string

identity principal assigned at creation

provide_mode
ProvideMode
one of
value
value
value
value
value
value
proxy_client
ProxyClient
change_id
integer
create_time
string

datetime

proxy_id
string

udid

client_id
string

udid

api_base_url
string
block
string
api_port
integer
http_proxy_url
string
https_proxy_url
string
socks_proxy_url
string
auth_token
string
instance_id
string

udid. The instance_id of the proxy device.

proxy_host
string
socks_proxy_port
integer
http_proxy_port
integer
https_proxy_port
integer
wg_config
object
wg_proxy_port
integer
client_private_key
string
client_public_key
string
client_ipv4
string
proxy_public_key
string
config
string

The WireGuard config file for this client.

resident
object
client_id
string

udid

instance_id
string

udid

resident_id
string

udid

resident_host
string
resident_service
string
resident_block
string
resident_internal_ports
array<integer>
array
integer
connections
array<object>
array
client_id
string

udid

connection_id
string

udid

connect_time
string
disconnect_time
string
connection_host
string
connection_service
string
connection_block
string'
GET/network/peersBearer authNetwork Peers

Fast network peer discovery.

Lists the currently connected network peers: the top-level clients of the network (clients with no sourceclientid) and their identity metadata (provide modes, principal, roles), plus disconnect markers for peers that disconnected within the recent window.

Allowed for network sessions and top-level client sessions. A client session's own client is excluded from the list.

Responses1 status · show schema
200
peers
array<NetworkPeer>

connected peers

array
client_id
string

udid

provide_modes
array<ProvideMode>

the peer's enabled provide modes

array
one of
value
value
value
value
value
value
principal
string

identity principal assigned at creation

roles
array<string>

identity roles assigned at creation

array
string
device_name
string
device_spec
string
disconnect_time
string

set when the entry is a disconnect marker for a recently disconnected peer

disconnected
array<NetworkPeer>

disconnect markers within the recent window

array
client_id
string

udid

provide_modes
array<ProvideMode>

the peer's enabled provide modes

array
one of
value
value
value
value
value
value
principal
string

identity principal assigned at creation

roles
array<string>

identity roles assigned at creation

array
string
device_name
string
device_spec
string
disconnect_time
string

set when the entry is a disconnect marker for a recently disconnected peer

disconnected_count
integer
error
object
message
string
GET/network/provider-locationsPublicNetwork Provider Locations

A list of locations and groups where there are at least one active provider in good health. Note that a location or group will need to be mapped to an actual provider using /network/find-providers.

Responses1 status · show schema
200
groups
array<object>
array
location_group_id
string

udid

name
string
provider_count
integer
promoted
boolean
match_distance
integer
locations
array<object>
array
location_id
string

udid

location_type
string
enum: city, region, country
name
string
city
string
city_location_id
string

udid

region
string
region_location_id
string

udid

country
string
country_location_id
string

udid

country_code
string
provider_count
integer
match_distance
integer
stable
boolean
strong_privacy
boolean
devices
array<object>
array
client_id
string

udid

device_name
string
country_count
integer
region_count
integer
city_count
integer
stable_count
integer
strong_privacy_count
integer
POST/network/find-provider-locationsPublicNetwork Find Provider Locations

Search for locations and groups that match a query, where there are at least one active provider in good health. The match algorithm accounts for typos and misspelling, and the tolerance can be tuned in the input. Note that a location or group will need to be mapped to an actual provider using /network/find-providers.

Request bodyshow schema
query
string
max_distance_fraction
number
enable_max_distance_fraction
boolean
rank_mode
string
Responses1 status · show schema
200
groups
array<object>
array
location_group_id
string

udid

name
string
provider_count
integer
promoted
boolean
match_distance
integer
locations
array<object>
array
location_id
string

udid

location_type
string
enum: city, region, country
name
string
city
string
city_location_id
string

udid

region
string
region_location_id
string

udid

country
string
country_location_id
string

udid

country_code
string
provider_count
integer
match_distance
integer
stable
boolean
strong_privacy
boolean
devices
array<object>
array
client_id
string

udid

device_name
string
country_count
integer
region_count
integer
city_count
integer
stable_count
integer
strong_privacy_count
integer
POST/network/find-providers2PublicNetwork Find Providers 2

Randomly sample providers for locations, groups, or devices, which are active and in good health. This allows random iteration by using the exclude input to mark visited providers.

Request bodyshow schema
specs
array<ProviderSpec>
array
location_id
string

udid

location_group_id
string

udid

client_id
string

udid

best_available
boolean
count
integer
force_count
boolean
exclude_client_ids
array<string>
array
string

udid

exclude_destinations
array<array<string>>
array
array
string

udid

rank_mode
string
enum: quality, speed
force_minimum
boolean
Responses1 status · show schema
200
providers
array<object>
array
client_id
string

udid

estimated_bytes_per_second
integer
has_estimated_bytes_per_second
boolean
tier
integer
intermediary_ids
array<string>
array
string

udid

location
ProviderLocation
country
string
country_code
string

lowercase iso 3166-1 alpha-2

region
string
city
string
country_location_id
string

udid

region_location_id
string

udid

city_location_id
string

udid

region_coordinates
LocationCoordinates
lat
number
lon
number
city_coordinates
LocationCoordinates
lat
number
lon
number
GET/network/rankingBearer authNetwork Get Ranking

Get leaderboard ranking of current network. Besides the data leaderboard rank, the result carries the network's points leaderboard settings (points_leaderboard_public, emoji_tag) and its points ranks (rank_points, rank_blocks, rank_streak; 0 until the network has points and a ranking snapshot exists).

Responses1 status · show schema
200
network_ranking
NetworkRanking
net_mib_count
number (float)
leaderboard_rank
integer
leaderboard_public
boolean

Whether your network is publicly visibile on the leaderboard

points_leaderboard_public
boolean

Whether the network is listed on the points leaderboard

emoji_tag
string

The network's emoji tag (1 to 6 emoji), absent when unset

rank_points
integer (int64)

Competition rank by total points, 0 when unranked

rank_blocks
integer (int64)

Competition rank by finalized epochs with points, 0 when unranked

rank_streak
integer (int64)

Competition rank by current streak, 0 when unranked

error
object
message
string
POST/network/ranking-visibilityBearer authNetwork Ranking Visibility

Allow network to toggle leaderboard ranking visibility

Request bodyshow schema
is_public
boolean

User can set whether their network is visible on the leaderboard

Responses1 status · show schema
200
error
object
message
string
POST/network/points-ranking-visibilityBearer authNetwork Points Ranking Visibility

Turn the network's name on or off on the points leaderboard. Every network with points is ranked and listed either way; this switch only decides whether its row shows the network name or "Anonymous". The emoji tag (/network/emoji) shows on the row regardless.

Request bodyshow schema
public
boolean

true to list the network on the points leaderboard

Responses1 status · show schema
200
points_leaderboard_public
boolean
error
object
message
string
POST/network/emojiBearer authNetwork Set Emoji Tag

Set the network's emoji tag: 1 to 6 emoji (each grapheme cluster must be a single emoji: pictographs with skin tones, ZWJ sequences, keycaps, flags). Letters, digits and punctuation are rejected with the message "Use 1 to 6 emoji.". An empty string clears the tag. The tag is shown on the points leaderboard row and in the network's own header.

Request bodyshow schema
emoji_tag
string

1 to 6 emoji; an empty string clears the tag

Responses1 status · show schema
200
emoji_tag
string

The stored (NFC-normalized) tag, empty when cleared

error
object
message
string
POST/network/block-locationBearer authNetwork Block Location

Block providing to a location

Request bodyshow schema
location_id
string

uuid

Responses1 status · show schema
200
error
object
message
string
POST/network/unblock-locationBearer authNetwork Unblock Location

Unblock providing to a location

Request bodyshow schema
location_id
string

uuid

Responses1 status · show schema
200
error
object
message
string
GET/network/blocked-locationsBearer authNetwork Blocked Locations

Get list locations to block from providing for the network

Responses1 status · show schema
200
blocked_locations
array<BlockedLocation>
array
location_id
string

uuid

location_name
string
location_type
string
country_code
string
error
object
message
string
GET/network/reliabilityBearer authNetwork Reliability

Get network reliability stats

Responses1 status · show schema
200
reliability_window
ReliabilityWindow
mean_reliability_weight
number (float)
min_time_unix_milli
integer
min_bucket_number
integer
max_time_unix_milli
integer
max_bucket_number
integer
bucket_duration_seconds
integer
max_client_count
integer
max_total_client_count
integer
reliability_weights
array<number (float)>
array
number (float)
client_counts
array<integer>
array
integer
total_client_counts
array<integer>
array
integer
country_multipliers
array<CountryMultiplier>
array
country_location_id
string

uuid

country
string
country_code
string
reliability_multiplier
number (float)
error
object
message
string
GET/network/userBearer authGet Network User

Get the user and configured auth methods for the caller network.

Responses1 status · show schema
200
network_user
object
user_id
string

udid

user_auth
string

email or phone number

verified
boolean
auth_type
string
network_name
string
wallet_address
string
user_auths
array<object>
array
user_auth
string
auth_type
string
sso_auths
array<object>
array
user_id
string

udid

auth_type
string
auth_jwt
string
user_auth
string
wallet_auths
array<object>
array
user_id
string

udid

wallet_address
string
blockchain
string
error
object
message
string
POST/network/user/updateBearer authUpdate Network Name

Update the caller network's name.

Request bodyshow schema
network_name
string
Responses1 status · show schema
200
error
object
message
string

Stats

7 operations
GET/stats/last-90PublicStats Last 90

Get network statistics for the last 90 days. The statistics are updated approximately every 60s.

Responses1 status · show schema
200
lookback
integer
created_time
integer

Unix epoch time UTC

all_transfer_data
map

yyyy-mm-dd to count

map
integer
all_transfer_summary
integer
all_transfer_summary_rate
integer
providers_data
map

yyyy-mm-dd to count

map
integer
providers_summary
integer
countries_data
map

yyyy-mm-dd to count

map
integer
countries_summary
integer
regions_data
map

yyyy-mm-dd to count

map
integer
regions_summary
integer
cities_data
map

yyyy-mm-dd to count

map
integer
cities_summary
integer
networks_data
map

yyyy-mm-dd to count

map
integer
networks_summary
integer
devices_data
map

yyyy-mm-dd to count

map
integer
devices_summary
integer
GET/stats/providersBearer authStats Providers

Get all providers in the caller network. Each provider includes stats from the last 24 hours.

Responses1 status · show schema
200
created_time
string

datetime

providers
array<object>
array
client_id
string

udid

connected
boolean
connected_events_last_24h
array<object>
array
event_time
string

datetime

connected
boolean
uptime_last_24h
number

hours up

transfer_data_last_24h
number

gib

payout_last_24h
number

usdc

search_interest_last_24h
integer

matching search count

contracts_last_24h
integer
clients_last_24h
integer
POST/stats/providers-last-nBearer authStats Providers Last N hours

Get all providers in the caller network. Each provider includes stats from the last n hours.

Request bodyshow schema
last_n
number

n hours

Responses1 status · show schema
200
created_time
string

datetime

providers
array<object>
array
client_id
string

udid

connected
boolean
connected_events_last_24h
array<object>
array
event_time
string

datetime

connected
boolean
uptime_last_24h
number

hours up

transfer_data_last_24h
number

gib

payout_last_24h
number

usdc

search_interest_last_24h
integer

matching search count

contracts_last_24h
integer
clients_last_24h
integer
POST/stats/provider-last-nBearer authStats Provider Last N hours

Get detailed stats on a single provider in the caller network. This is meant to give the user complete visibility over usage.

Request bodyshow schema
client_id
string

udid

last_n
number

n hours

Responses1 status · show schema
200
lookback
integer
created_time
string

datetime

uptime
map

yyyy-mm-dd-hh (utc) to minutes

map
number
transfer_data
map

yyyy-mm-dd to gib

map
number
payout
map

yyyy-mm-dd to payout USDC

map
number
search_interest
map

yyyy-mm-dd to matching search count

map
integer
contracts
map

yyyy-mm-dd to count

map
integer
clients
map

yyyy-mm-dd to count

map
integer
client_details
array<object>
array
client_id
string

udid

transfer_data
map

yyyy-mm-dd to gib

map
number
POST/stats/providers-overview-last-nBearer authStats Providers Overview Last N hours

Get a network-wide time series aggregated across all providers in the caller network, over the last n hours.

Request bodyshow schema
last_n
number

n hours

Responses1 status · show schema
200
lookback
integer
created_time
string

datetime

uptime
map

yyyy-mm-dd to avg hours up per provider

map
number
transfer_data
map

yyyy-mm-dd to gib

map
number
payout
map

yyyy-mm-dd to payout USDC

map
number
search_interest
map

yyyy-mm-dd to matching search count

map
integer
contracts
map

yyyy-mm-dd to count

map
integer
clients
map

yyyy-mm-dd to count

map
integer
POST/stats/leaderboardBearer authStats Leaderboard

Fetches top 100 current leaderboard. This data is refreshed every payout.

Request bodyshow schema
empty object
Responses1 status · show schema
200
earners
array<LeaderboardEarner>
array
network_id
string

uuid

network_name
string
net_mib_count
number (float)
is_public
boolean

Whether the network has opted in to being displayed on the leaderboard or not

contains_profanity
boolean

Whether the network name contains profanity

rank
integer

The caller network's leaderboard position (1 = top earner); 0 when the network has no ranked payouts.

total
integer

The number of ranked networks.

error
object
message
string
POST/stats/points-leaderboardBearer authStats Points Leaderboard

Page the all-time points leaderboard. Every network with points is ranked on three dimensions (total points, finalized epochs with points = "blocks", current streak of consecutive finalized epochs with points) with competition ranks (1, 2, 2, 4), and every ranked network is listed: the pages form one continuous list. A row carries the network name only when that network turned on /network/points-ranking-visibility (its "show my network name" switch); otherwise the row is anonymous. The emoji tag (/network/emoji) shows on every row that set one. Each sort has its own tie-break order, every key descending, then the network id ascending so the order is total: points = (points, streak, blocks), blocks = (blocks, streak, points), streak = (streak, blocks, points). The pages come in exactly that order, and a rank is shared only by networks whose three values all tie. Pages use a keyset cursor pinned to a ranking snapshot (rebuilt when an epoch finalizes, when a payout plan commits, and hourly); a cursor whose snapshot was pruned returns restart: true and the client reloads from the top. No authentication is required; with a bearer token the response also carries me, the caller's own row with its network name for the caller's own card, whether or not it opted in. In the list itself the caller's row is anonymous like everyone else's until it opts in: the caller sees what everyone sees, and the apps only highlight that row.

Request bodyshow schema
sort
string

The dimension to page by

enum: points, blocks, streak
cursor
string

Continues a previous page in either direction: a next_cursor opens the page after it, a prev_cursor the page before it. Omit for the first page. A cursor is opaque and pins the snapshot and the sort; restart: true means its snapshot is gone.

seek_rank
integer (int64)

Jumps to a position: the page starts at the row whose position in this sort's total order equals seek_rank (1-based, clamped to [1, totalranked]). Used without a cursor; the response then carries both `prevcursor and nextcursor so the jumped-to window pages in both directions. totalranked` from any previous response is the client's denominator when it turns a scroll position into a rank.

limit
integer

Page size, default 50, max 200

Responses1 status · show schema
200
rows
array<PointsLeaderboardRow>
array
network_id
string
network_name
string

Present only when the network turned on pointsleaderboardpublic (/network/points-ranking-visibility)

emoji_tag
string

The network's emoji tag, absent when unset; shown whether or not the name is

anonymous
boolean

true when the network name is hidden; the row is listed either way

contains_profanity
boolean

The public name contains profanity (apps may mask it)

total_points
number (double)

All-time points

blocks_with_points
integer

Finalized epochs in which the network earned points

streak
integer

Consecutive finalized epochs with points ending at the latest finalized epoch

longest_streak
integer

The best streak ever (informational, never ranked)

rank_points
integer (int64)
rank_blocks
integer (int64)
rank_streak
integer (int64)
position
integer (int64)

The row's 1-based place in the requested sort's total order. Ranks tie (competition ranks), positions never do: this is the seek_rank coordinate and the key a client keeps its loaded window by.

next_cursor
string

Pages forward from this page's last row; absent on the last page

prev_cursor
stringnull

Pages backward from this page's first row; null when the page starts at position 1. Present on every page reached by a cursor or a seek_rank.

restart
boolean

The cursor's snapshot is gone; reload from the top

total_ranked
integer (int64)

Networks ranked in the snapshot; every one of them is listed across the pages

snapshot_time
string (date-time)
latest_epoch
integer (int64)

The latest finalized epoch the snapshot counts

me
PointsLeaderboardMe
network_id
string
network_name
string

Present only when the network turned on pointsleaderboardpublic (/network/points-ranking-visibility)

emoji_tag
string

The network's emoji tag, absent when unset; shown whether or not the name is

anonymous
boolean

true when the network name is hidden; the row is listed either way

contains_profanity
boolean

The public name contains profanity (apps may mask it)

total_points
number (double)

All-time points

blocks_with_points
integer

Finalized epochs in which the network earned points

streak
integer

Consecutive finalized epochs with points ending at the latest finalized epoch

longest_streak
integer

The best streak ever (informational, never ranked)

rank_points
integer (int64)
rank_blocks
integer (int64)
rank_streak
integer (int64)
position
integer (int64)

The row's 1-based place in the requested sort's total order. Ranks tie (competition ranks), positions never do: this is the seek_rank coordinate and the key a client keeps its loaded window by.

points_leaderboard_public
boolean
ranked
boolean

false when the network has no points yet

error
object
message
string

Subscription

9 operations
GET/subscription/balanceBearer authsubscriptionBalance

Get the current subscription status and transfer balance. This is also the PLAN response of the onboarding program: it carries the caller's regional price_tier, the welcome onboarding_offer (null when none was issued) and the experiments assignments per surface.

Regional pricing rule (mmm/onboarding/PLAN.md): the tier is resolved, in order, from storefront_country (the store's storefront country, sent by the Apple and Google apps), the Stripe customer's billing country when a customer exists, else the client IP as a DISPLAY ESTIMATE (price_tier.estimate: true). The store charges its own storefront's price; the Stripe tier actually charged is finalized from the card's billing country once the payment method is attached, before the trial ends. The regional price is tied to the storefront/billing country, never to a VPN exit.

Parameters
storefront_country(query)
string

ISO 3166-1 alpha-2 (or alpha-3) storefront country of the app's store (StoreKit Storefront.countryCode, Play billing region).

Responses1 status · show schema
200
start_balance_byte_count
integer

The initial data balance in bytes for the period.

balance_byte_count
integer

The current data balance in bytes.

open_transfer_byte_count
integer

Data tied up in pending contracts.

current_subscription
object
subscription_id
string

udid

store
string
plan
string
active_transfer_balances
array<object>
array
balance_id
string

udid

network_id
string

udid

start_time
string
end_time
string
start_balance_byte_count
integer
net_revenue_nano_cents
integer
subsidy_net_revenue_nano_cents
integer
balance_byte_count
integer
purchase_token
string
paid
boolean
pending_payout_usd_nano_cents
integer
update_time
string
price_tier
PriceTier
name
string
enum: standard, regional
yearly_usd
number
monthly_usd
number
currency
string

always USD

source
string

how the country was resolved

enum: storefront, billing, ip, default
estimate
boolean

true when the tier is a display estimate (ip or default)

onboarding_offer
one of

The caller's welcome offer; null when none was issued.

one of
issued_at
string (date-time)
expires_at
string (date-time)
percent_off
integer
months_free
integer
first_year_usd
number
regular_year_usd
number
tier
string
currency
string
state
string
enum: active, redeemed, expired
apple_offer_code
string
play_offer_tag
string
stripe_coupon_id
string
redeemed_at
one of

When the offer was first redeemed; null until then.

one of
string (date-time)
null
store
one of

The store of the first redemption; null until then.

one of
string
enum: apple, play, stripe, solana
null
null
experiments
map

The caller's variant per experiment surface, keyed by surface (offer.in_app, email.sequence, offer.intro_step, offer.final_screen, offer.email, offer.account, email., cadence). Only running experiments appear. A network keeps its variant for the life of an experiment (hash(networkid, experimentid), server-side). The variant holdout on offer.in_app means: show the regular plan picker, no offer screen, do not issue the offer in-app. Stamp the surface's experiment_id/variant on offer.screen.shown.

map
experiment_id
string
variant
string

a registry variant name; holdout means show nothing

GET/subscription/detailsBearer authSubscription Details

The "Manage subscription" screen: every store currently billing the caller's network, one entry per store, with the window it bought (end_time is the expiry, or the next renewal date when the store renews), the store's auto-renew state and the control that stops it.

auto_renew is true/false when the store answered and null when the store lookup failed (best-effort, ~5 s per store; the entry still carries the window from our own records). can_cancel is true only for Stripe, which /subscription/cancel acts on; Apple and Google entries carry the store's own subscriptions page in manage_url (a subscription is cancelled where it is billed); a Solana entry is a one-time USDC payment that never renews. has_stripe_customer gates the Stripe billing portal (/stripe/customer-portal errors without one).

The result is cached per network for 60 seconds; cancel and resume invalidate it.

Responses1 status · show schema
200
subscriptions
array<object>

One entry per store billing the network, ordered by store.

array
store
string

stripe | apple | google | solana | manual | x402 | "" (unknown)

plan
string

The wire plan value ("supporter"); shown as Pro.

cadence
string

yearly | monthly | "" when unknown.

start_time
string

datetime, the start of the active window

end_time
string

datetime, the expiry or the next renewal date

auto_renew
boolean

The store will bill again at end_time; null when the store lookup failed.

cancel_at_period_end
boolean

The store lets the paid period run out and will not bill again.

can_cancel
boolean

POST /subscription/cancel acts on this entry (Stripe only).

manage_url
string

The store's own subscriptions page (Apple, Google), else empty.

transaction_id
string

The store handle for support; invoice id, original transaction id, purchase token or payment reference.

has_stripe_customer
boolean

A Stripe customer exists for the network; gate for /stripe/customer-portal.

update_time
string

datetime

POST/subscription/cancelBearer authSubscription Cancel

Stop the Stripe subscription billing the caller's network at the end of the paid period (cancel_at_period_end); the customer keeps Pro until end_time. Only store "stripe" (the default) is acted on: the other stores answer with error.message and, for Apple/Google, the store's subscriptions page in manage_url. Idempotent: an already-cancelling subscription is not written again.

Request bodyshow schema
store
string

The store to act on. "stripe" (default) is the only store the server can cancel.

Responses1 status · show schema
200
store
string
end_time
string

datetime, the end of the paid period (Pro is kept until then)

auto_renew
boolean
manage_url
string

For a store the server cannot act on, where the customer cancels.

error
object
message
string
POST/subscription/resumeBearer authSubscription Resume

Undo /subscription/cancel while the paid period is still running: the Stripe subscription renews again. Same request and result shapes.

Request bodyshow schema
store
string

The store to act on. "stripe" (default) is the only store the server can cancel.

Responses1 status · show schema
200
store
string
end_time
string

datetime, the end of the paid period (Pro is kept until then)

auto_renew
boolean
manage_url
string

For a store the server cannot act on, where the customer cancels.

error
object
message
string
POST/subscription/check-balance-codeBearer authSubscription Check Balance Code

Check if the balance code is valid.

Request bodyshow schema
secret
string
Responses1 status · show schema
200
balance
object
start_time
string
end_time
string
balance_byte_count
integer
error
object
message
string
POST/subscription/redeem-balance-codeBearer authSubscription Redeem Balance Code

Redeem the balance code and add the transfer balance to the caller network.

Request bodyshow schema
secret
string
Responses1 status · show schema
200
transfer_balance
object
transfer_balance_id
string

udid

start_time
string
end_time
string
balance_byte_count
integer
error
object
message
string
POST/subscription/create-payment-idBearer authSubscription Create Payment Id

Creates an anonymous payment identifier to be used with purchases. This keeps network information out of the payment processor system. For example in Google Play this is called the "obfuscated account id".

Request bodyshow schema
empty object
Responses1 status · show schema
200
subscription_payment_id
string

udid

error
object
message
string
POST/subscription/stripe/payment-sheetBearer authstripePaymentSheet

Prepare an inline Stripe PaymentSheet purchase of Pro (the non-Play Android flavors, Windows and Linux; never the play flavor or iOS/macOS). The server creates or reuses the Stripe customer (metadata network_id) and the subscription at the caller's regional tier price: the yearly plan with the 14-day trial and, when the caller's welcome offer is redeemable, the 25% coupon applied server-side; the monthly plan without a trial. The sheet confirms the returned intent: a SetupIntent for the yearly plan (intent_type: setup, setup_intent_client_secret) or the first invoice's PaymentIntent for the monthly plan (intent_type: payment, payment_intent_client_secret). Configure the sheet with customer_id, ephemeral_key_secret and publishable_key; pass the Stripe API version the mobile SDK requires as stripe_version.

The trial is credited only once the card is attached (setup_intent.succeeded); an abandoned sheet leaves nothing behind. The charged tier is finalized from the card's billing country before the trial ends and the tier is recorded on the subscription. Calling again replaces a pending, unfinished sheet.

Request bodyshow schema
plan
OfferPlan
string
enum: yearly, monthly
storefront_country
string
stripe_version
string

the Stripe API version the mobile SDK requires for its ephemeral key

Responses3 statuses · show schema
200
customer_id
string
ephemeral_key_secret
string
setup_intent_client_secret
string

set for intent_type setup (the yearly plan with its trial)

payment_intent_client_secret
string

set for intent_type payment (the monthly plan, no trial)

intent_type
string
enum: setup, payment
subscription_id
string
publishable_key
string
tier
string
currency
string
plan
string
amount_first_period_usd
number

the first period's price, with the welcome offer applied when eligible

regular_period_usd
number
trial_days
integer
trial_end_at
string (date-time)
offer_applied
boolean
error
one of
one of
message
string
null
401
No body
429
error
object
message
string
retry_after_seconds
integer
GET/subscription/stripe/pricesBearer authstripePrices

The Stripe price ids (and USD amounts) of the caller's regional tier, the publishable key, and the welcome-offer coupon id when the caller's offer is redeemable -- for clients that build their own Stripe flow (the Windows/Linux Payment Element).

Parameters
storefront_country(query)
string

ISO 3166-1 alpha-2 storefront country, when the app knows it.

Responses2 statuses · show schema
200
tier
string
currency
string
yearly_price_id
string
monthly_price_id
string
yearly_usd
number
monthly_usd
number
publishable_key
string
onboarding_coupon_id
string

the welcome-offer coupon, when the caller's offer is redeemable (yearly only)

offer_eligible
boolean
error
one of
one of
message
string
null
401
No body

Wallet

4 operations
GET/wallet/balanceBearer authWallet Balance

Get the balance for the USDC user custody wallet. The user custody wallet allows URnetwork to query the balance, but the user must take actions against the wallet.

Responses1 status · show schema
200
wallet_info
object
wallet_id
string
token_id
string
blockchain
string
blockchain_symbol
string
create_date
string
balance_usdc_nano_cents
integer
address
string
POST/wallet/validate-addressBearer authWallet Validate Address

Validate a USDC wallet address on the user custody wallet chain. This can be used to check whether an address can receive a transfer out from the user custody wallet. Please use this before initiating any transfer out to avoid lost funds.

Request bodyshow schema
address
string
chain
string

Optional. The Circle blockchain param for the address. See https://developers.circle.com/w3s/reference/createvalidateaddress

Responses1 status · show schema
200
valid
boolean
POST/wallet/circle-initBearer authWallet Circle Init

Initialize the Circle USDC user self custody wallet. This starts a process that must be completed by the user.

Responses1 status · show schema
200
user_token
object
user_token
string
encryption_key
string
challenge_id
string
error
object
message
string
POST/wallet/circle-transfer-outBearer authWallet Circle Transfer Out

Set up a transfer from the Circle USDC user self custody wallet to an address. This starts a process that must be completed by the user.

Request bodyshow schema
to_address
string
amount_usdc_nano_cents
integer
terms
boolean

user consent to accept terms of transfer

Responses1 status · show schema
200
user_token
object
user_token
string
encryption_key
string
challenge_id
string
error
object
message
string

Device

14 operations
POST/device/addBearer authDevice Add

Add a device, which can either be owned by the network or shared with the network. The code provided can be either adoption code or a share code. Once a code is added, the device becomes an associated device until confirmation. If the device is a shared device, it will remain an associated device after confirmation.

Request bodyshow schema
code
string

share code or adopt code

Responses1 status · show schema
200
code_type
string
enum: share, adopt
code
string
device_name
string

Name of the device shared by the owner

associated_network_name
string

The name of the source network. Only for share codes.

client_id
string

udid. Only for share codes.

duration_minutes
number
error
object
message
string
POST/device/create-share-codeBearer authDevice Create Share Code

Creates a code to share a device.

Request bodyshow schema
client_id
string

udid

device_name
string

Name of the device that will be shared to the guest

Responses1 status · show schema
200
share_code
string
error
object
message
string
GET/device/share-code/{code}/qr.pngBearer authDevice Share Code QR

A QR code that maps to a URL to add the shared device. Send it to someone to scan to add the device.

Parameters
code(path)
string

Share code

required
Responses1 status · show schema
200
string (binary)
POST/device/share-statusBearer authDevice Share Status

The status of the shared device. The status can be one of:

  • unassociated
  • associated pending confirmation
  • associated
Request bodyshow schema
share_code
string
Responses1 status · show schema
200
pending
boolean
associated_network_name
string
error
object
message
string
POST/device/confirm-shareBearer authDevice Confirm Share

Confirm the share of a device. This must be called from the side that initiates the share.

Request bodyshow schema
share_code
string
associated_network_name
string
Responses1 status · show schema
200
associated_network_name
string
error
object
message
string
POST/device/create-adopt-codePublicDevice Create Adopt Code

Creates a code to adopt a device. The adopt code is valid for a limited time.

Request bodyshow schema
device_name
string

Name of the device that will be shared to the adopter

device_spec
string
Responses1 status · show schema
200
adopt_code
string
adopt_secret
string

keep this secret locally to use with confirm

duration_minutes
number
error
object
message
string
GET/device/adopt-code/{code}/qr.pngPublicDevice Adopt Code QR

A QR code that maps to a URL to adopt the device. Send it to someone to scan to adopt the device.

Parameters
code(path)
string

Adopt code

required
Responses1 status · show schema
200
string (binary)
POST/device/adopt-statusPublicDevice Adopt Status

The status of the adopt-code device. The status can be one of:

  • unassociated
  • associated pending confirmation
  • associated
Request bodyshow schema
adopt_code
string
Responses1 status · show schema
200
pending
boolean
associated_network_name
string
error
object
message
string
POST/device/confirm-adoptPublicDevice Confirm Adopt

Confirm the adoption of a device. This must be called from the side that initiates the adoption.

Request bodyshow schema
adopt_code
string
adopt_secret
string
associated_network_name
string
Responses1 status · show schema
200
by_client_jwt
string

client auth

error
object
message
string
POST/device/remove-adopt-codePublicRemove Adopt Code

Remove an adopt code. This must be called from the side that initiates the adoption.

Request bodyshow schema
adopt_code
string
adopt_secret
string
Responses1 status · show schema
200
error
object
message
string
GET/device/associationsBearer authDevice Associations

The devices associated with the caller network. Associated devices are:

  • pending adoption devices
  • incoming shared devices (not owned by the caller network)
  • outgoing shared devices (owned by the caller network)
Responses1 status · show schema
200
pending_adoption_devices
array<object>

devices pending adoption that need to be confirmed by the offerer

array
pending
boolean
code
string
device_name
string

Name of the device

duration_minutes
number
incoming_shared_devices
array<object>

devices owned by another network shared to the caller network

array
pending
boolean
code
string
device_name
string

Name of the device

client_id
string

udid

network_name
string
outgoing_shared_devices
array<object>

devices owned by the caller network shared to another network

array
pending
boolean
code
string
device_name
string

Name of the device

client_id
string

udid

network_name
string
POST/device/remove-associationBearer authDevice Remove Association

Remove a device association. The association can be any of:

  • pending adoption device
  • incoming shared device (not owned by the caller network)
  • outgoing shared device (owned by the caller network)
Request bodyshow schema
code
string
Responses1 status · show schema
200
error
object
message
string
POST/device/set-association-nameBearer authDevice Set Association Name

Set the name of the association. To set the name of devices owned by the network, use /device/set-name.

Request bodyshow schema
code
string
device_name
string

Name of the device

Responses1 status · show schema
200
error
object
message
string
POST/device/set-nameBearer authNetwork Set Device Name

Sets the name of a device owned by the network. To set the name of devices shared with the network, use /device/set-association-name.

Request bodyshow schema
device_id
string

udid

device_name
string
Responses1 status · show schema
200
error
object
message
string

Account

19 operations
POST/account/change-nameBearer authAccount Change Name

Change the network name of the calling network. The previous name enters a reclaim cooldown. Subject to the account action rate limit.

Request bodyshow schema
network_name
string
new_name
string
Responses1 status · show schema
200
network_name
string
error
object
message
string
POST/account/claim-nameBearer authAccount Claim Name

Claim an unused network name for the calling network. Shares the change-name budget and rate limit.

Request bodyshow schema
network_name
string
new_name
string
Responses1 status · show schema
200
network_name
string
error
object
message
string
POST/account/api-keyBearer authAccount Create API Key

Create an API key for the account.

Request bodyshow schema
name
string
Responses1 status · show schema
200
id
string

uuid

api_key
string
name
string
error
object
message
string
POST/account/api-key/removeBearer authAccount Remove API Key

Remove an API key for the account.

Request bodyshow schema
id
string

uuid

Responses1 status · show schema
200
error
object
message
string
GET/account/api-keysBearer authAccount Get API Keys

Fetches a list of API keys associated with the account. The list does not include the API key secrets, only metadata.

Responses1 status · show schema
200
api_keys
array<PublicAccountApiKey>
array
id
string

uuid

name
string
create_time
string

datetime

error
object
message
string
GET/account/payout-walletBearer authAccount Get Payout Wallet

Fetches the payout wallet associated with the network

Responses1 status · show schema
200
wallet_id
string

udid

POST/account/payout-walletBearer authAccount Set Payout Wallet

Set an existing account wallet as the wallet to receive network payments.

Request bodyshow schema
wallet_id
string

udid

Responses1 status · show schema
200
empty object
GET/account/pointsBearer authAccount Get Points

Retrieves account points earned. Eventually, users will be able to convert points for tokens

Responses1 status · show schema
200
network_points
array<AccountPoint>
array
account_point_id
string

uuid

network_id
string

uuid

event
string
enum: referral, payout, payout_linked_account, payout_multiplier, payout_reliability
point_value
integer
payment_plan_id
string

uuid

account_payment_id
string

uuid

linked_network_id
string

uuid

create_time
string

datetime

GET/account/paymentsBearer authAccount Get Payouts

Retrieves list of account payments

Responses1 status · show schema
200
account_payments
array<AccountPayment>
array
payment_id
string
payment_plan_id
string
wallet_id
string
network_id
string
payout_byte_count
integer
payout_nano_cents
integer
subsidy_payout_nano_cents
integer
reliability_subsidy_nano_cents
integer
min_sweep_time
string (date-time)
create_time
string (date-time)
payment_record
string
token_type
string
token_amount
number (float)
payment_time
string (date-time)
payment_receipt
string
wallet_address
string
blockchain
string
enum: MATIC, SOL
tx_hash
string
completed
boolean
complete_time
string (date-time)
canceled
boolean
cancel_time
string (date-time)
error
GetNetworkAccountPaymentsError
message
string
POST/account/walletBearer authAccount Create Wallet

Create a new wallet for your network. You can then use it as a payout wallet by posting to /account/payout-wallet.

Request bodyshow schema
blockchain
string

The blockchain associated with the address

enum: SOL, MATIC
wallet_address
string

The "SOL" or "MATIC" wallet address

default_token_type
string

We only support "USDC"

enum: USDC
Responses1 status · show schema
200
wallet_id
string

udid

GET/account/walletsBearer authAccount Get Wallets

Get a list of wallets associated with your network

Responses1 status · show schema
200
wallets
array<AccountWallet>

A list of wallets associated with your network

array
wallet_id
string

udid

circle_wallet_id
string

If the wallet was created through the Circle flow, it is the ID associated with the Circle wallet.

network_id
string

udid

wallet_type
string
enum: circle_uc, external
blockchain
string
enum: SOL, MATIC
wallet_address
string

Blockchain wallet address

active
boolean
default_token_type
string
enum: USDC
create_time
string

datetime

has_seeker_token
boolean
POST/account/wallets/removeBearer authAccount Remove Wallet

Remove a wallet from your list of account wallets

Request bodyshow schema
wallet_id
string

udid

Responses1 status · show schema
200
success
boolean

Wallet successfully removed

error
object
message
string
POST/account/wallets/verify-seekerBearer authAccount Verify Seeker Token

Verify that a wallet holds a Seeker token by validating a signed message.

Request bodyshow schema
wallet_address
string

The wallet public key

wallet_signature
string
wallet_message
string

The signed message

Responses1 status · show schema
200
success
boolean
error
object
message
string
GET/account/balance-codesBearer authAccount Balance Codes

Fetch balance codes redeemed by network

Responses1 status · show schema
200
balance_codes
array<NetworkRedeemedBalanceCode>
array
balance_code_id
string

uuid

balance_byte_count
integer
redeem_time
string

datetime

end_time
string

datetime

secret
string
error
NetworkBalanceCodesError
message
string
GET/account/epochsBearer authAccount Epochs

The caller network's finalized epochs, newest first: the points earned inside each epoch's wall-clock window and the network's share of the operator pool in basis points (0 when no coldkey was attached, i.e. points only). limit defaults to 26 and is capped at 104.

Parameters
limit(query)
integer
Responses1 status · show schema
200
epochs
array<AccountEpoch>
array
epoch
integer
start_millis
integer

Epoch window start, unix milliseconds.

end_millis
integer

Epoch window end, unix milliseconds.

points
number (double)

Points earned inside the window.

share_bps
integer

The network's share of the operator pool in basis points; 0 when no coldkey was attached.

error
object
message
string
GET/account/referral-codeBearer authAccount Referral Code

Unique network code to refer new users

Responses1 status · show schema
200
referral_code
string

udid

total_referrals
integer
max_referrals
integer

Referrals a network is paid for (pro.yml referral.max_referrals). 0 when the server has no pro.yml (uncapped); clients treat 0 as unknown.

bonus_per_referral_bytes
integer

Bytes granted to the referrer per referral, per bonus period. 0 when unknown.

referred_bonus_bytes
integer

Bytes granted to the referred network, per bonus period. 0 when unknown.

bonus_period_seconds
integer

The bonus grant period in seconds (24h = 86400). 0 when unknown.

GET/account/referral-networkBearer authAccount Referral Network

Get the network that was referred the authenticated network

Responses1 status · show schema
200
network
ReferralNetwork
id
string

uuid

name
string
error
object
message
string
POST/account/set-referralBearer authAccount Set Referral

Set the parent referral network for the authenticated network.

Request bodyshow schema
referral_code
string
Responses1 status · show schema
200
error
object
message
string

Preferences

2 operations
POST/preferences/set-preferencesBearer authPreferences Set

Set account preferences.

Request bodyshow schema
product_updates
boolean
Responses1 status · show schema
200
empty object
GET/preferencesBearer authPreferences Get

Get account preferences.

Responses1 status · show schema
200
product_updates
boolean

Feedback

1 operation
POST/feedback/send-feedbackBearer authFeedback Send

Feedback.

Request bodyshow schema
uses
object
personal
boolean
business
boolean
needs
object
private
boolean
safe
boolean
global
boolean
collaborate
boolean
app_control
boolean
block_data_brokers
boolean
block_ads
boolean
focus
boolean
connect_servers
boolean
run_servers
boolean
prevent_cyber
boolean
audit
boolean
zero_trust
boolean
visualize
boolean
other
string
star_count
integer
Responses1 status · show schema
200
feedback_id
string

udid

Connect protocol

3 operations
GET/connectPublicAuth Connect

Redirect (303) to the single sign-on (SSO) start URL. Used to begin the browser SSO/OAuth flow.

Responses1 status · show schema
303
No body
POST/connectPublicAuth Connect Post

Redirect (303) to the single sign-on (SSO) start URL. Used to begin the browser SSO/OAuth flow.

Responses1 status · show schema
303
No body
POST/connect/controlBearer authConnect Control

Out-of-band control messages for the connect protocol. Blocking request-response control messages need to be handled out-of-band to resolve the possibility of dedlocks in the client sequence.

Request bodyshow schema
pack
string

base64 encoded connect protobuf Pack processed as control messages. As an inline message, these would be sent to the control id.

Responses1 status · show schema
200
pack
string

base64 encoded connect Pack resulting from processing the control messages. As an inline message, this is what would be sent from the control id after processing the control messages.

error
object
message
string

Transfer

1 operation
GET/transfer/statsBearer authTransfer Stats

Retrieves the paid and unpaid byte count provided to the network

Responses1 status · show schema
200
paid_bytes_provided
integer
unpaid_bytes_provided
integer

Solana

1 operation
POST/solana/payment-intentBearer authsolanaPaymentIntent

When paying for a subscription with Solana, we track the order through this intent.

Request bodyshow schema
reference
string

A unique reference string to identify the payment intent added to the Solana transaction

plan
string

The plan. The PRICE is quoted by the server from the caller's regional tier. yearly_onboarding is the welcome offer (the tier's yearly price less 25%, crediting a year plus the 14-day trial) and is refused unless the caller's offer is redeemable.

enum: yearly, monthly, yearly_onboarding
storefront_country
string

ISO 3166-1 storefront country, when the app knows it (Solana keeps the estimate otherwise)

Responses2 statuses · show schema
200
amount_usd
number

the price the server quoted; the client must pay exactly this

tier
string
plan
string
regular_amount_usd
number

the plan's regular price (the full-year price for yearly_onboarding)

offer_applied
boolean
currency
string
error
one of
one of
message
string
null
401
No body

Referral codes

1 operation
POST/referral-code/validatePublicValidate Referral Code

Validate a referral (bonus) code: whether it exists and whether it has been used up. The sign-up screens call this before an account exists, so no authentication is required; a bearer token, if sent, is ignored. Checks are budgeted per caller address (60 per 10 minutes) and across all callers; over budget the response is 429 with a Retry-After header.

Request bodyshow schema
referral_code
string
Responses2 statuses · show schema
200
is_valid
boolean
is_capped
boolean
error
object
message
string
429
No body

Other

28 operations
GET/clockPublicClock

Get the cumulative destination-reported bytes for contracts finalized on or after the start of subnet block 9. The counter advances when contracts reach a final outcome and is intended for public clients polling every 1-5 seconds.

Responses2 statuses · show schema
200
total_transfer_byte_count
string

Base-10 destination-reported bytes for contracts finalized since since_block. This is a string so clients do not lose integer precision as the lifetime total grows.

since_block
integer

First subnet block included in the counter.

since_time
string (date-time)

UTC start time of since_block.

503
No body
POST/log/{clientId}/uploadBearer authLog Upload

Upload a log file for the caller, associated with a feedback id. The request body is the raw log file content, streamed to storage. Note the {clientId} path segment is actually the feedback id the log is attached to.

Parameters
clientId(path)
string

udid. The feedback id the log file is associated with.

required
Request bodyshow schema
string (binary)
Responses1 status · show schema
200
empty object
GET/key/{clientId}PublicGet Client Key

Fetch the published Ed25519 public key for a client id. Unauthenticated by design - the value is a public key meant to be fetchable by any peer. A client that has never published a key returns {"public_key": null} with HTTP 200.

Parameters
clientId(path)
string

udid. The client id to look up.

required
Responses1 status · show schema
200
public_key
string

base64 encoded Ed25519 public key for the client id. null when the client has never published a key.

GET/helloPublicHello

Simple hello to the network that returns some useful information. This can be used for discovery.

Responses1 status · show schema
200
client_address
string
GET/my-ip-infoPublicMy IP Info

Information about the caller's IP as seen by the platform: geolocation, privacy/VPN classification, whether the IP is currently connected to the network, and expected round-trip times to nearby landmarks.

Responses1 status · show schema
200
info
object
ip
string
location
object
coordinates
object
lat
number
lon
number
city
string
region
string
country
object
code
string
name
string
flag_url
string
continent
object
code
string
name
string
timezone
string
privacy
object
vpn
boolean
proxy
boolean
tor
boolean
relay
boolean
hosting
boolean
service
string
landmarks
array<object>
array
name
string
ip
string
url
string
rtt
number
ws_url
string
coordinates
array<number>
array
number
connected_to_network
boolean
POST/stripe/payment-intentBearer authStripe Payment Intent

When paying for a subscription with Stripe, create the payment intents, ephemeral key, and customer id needed to complete the purchase.

Request bodyshow schema
empty object
Responses1 status · show schema
200
payment_intents
array<StripePaymentIntent>
array
subscription_type
string
client_secret
string
ephemeral_key
string
customer_id
string
publishable_key
string
error
object
message
string
POST/stripe/customer-portalBearer authStripe Customer Portal

Create a Stripe customer portal URL for the caller to manage their subscription.

Request bodyshow schema
empty object
Responses1 status · show schema
200
url
string
error
object
message
string
POST/pay/data/checkoutPublicPay Data Checkout

Buy a data pack with a card without signing in (the ur.io buy-data page). Starts a hosted Stripe checkout and returns the url to send the customer to. To pay with USDC on Solana use /pay/data/solana-intent.

With network_name, the data is applied to that network by the payment webhook as soon as the payment confirms, and the customer is emailed a note that the data is on the network (the code is included, already applied). The name is matched case-insensitively and exactly; an unknown name returns error.message "No network named ".

Without network_name, the customer receives a data code by email, as before. Stripe collects the email on its checkout page when email is not given.

The success url is the configured checkout success url plus item= and, when applying to a network, network=. Unauthenticated, per-ip rate limited. Errors are returned as error.message with a 200.

Request bodyshow schema
item_id
string
enum: data_1tib, data_10tib
provider
string

the hosted checkout; empty means stripe

enum: stripe
network_name
string

the network that receives the data; omit to receive a code by email

email
string

where the code (or the applied note) is sent; Stripe collects it at checkout when omitted

Responses1 status · show schema
200
url
string

the hosted checkout url to send the customer to

provider
string
enum: stripe
network_id
string (uuid)

the resolved network when network_name was given

error
object
message
string
POST/pay/data/network-lookupPublicPay Data Network Lookup

Whether a network with exactly this name exists, for the buy-data page. Matched the same way /pay/data/checkout resolves network_name (case-insensitive, exact). Unlike /auth/network-check, which is a sign-up similarity check, a name within a few characters of an existing one is NOT reported as existing. Returns only the canonical name, no id. Unauthenticated, per-ip rate limited.

Request bodyshow schema
network_name
string
Responses1 status · show schema
200
exists
boolean
network_name
string

the name as stored, when it exists

POST/pay/data/solana-intentPublicPay Data Solana Intent

Buy a data pack with USDC on Solana, without signing in or giving an email: the data goes straight to the network named by network_name (matched like /pay/data/network-lookup). Records the payment intent and returns the exact amount_usd to send in USDC. The client generates reference (a Solana Pay reference: a fresh base58 public key) and either opens a Solana Pay url carrying it, or shows the buyer the receiving address, the amount and memo (which is the reference) to send by hand from any wallet or exchange. The Helius webhook (/pay/solana) matches the transfer by the reference among the transaction's account keys OR by the memo text, then lands the data on the network (data only, valid for one year, no Pro) and emails the network's admin when their login is an email.

The intent expires after 24 hours (expires_at); a payment that arrives late still credits as long as the intent has not been swept. A reused reference, an unknown item or an unknown network return error.message with a 200. Unauthenticated, per-ip rate limited.

Request bodyshow schema
item_id
string
enum: data_1tib, data_10tib
network_name
string

the network that receives the data

reference
string

the Solana Pay reference the client generated (a fresh base58 public key); it doubles as the transfer memo for a payment sent by hand

Responses1 status · show schema
200
amount_usd
number

the exact amount to send, in USDC

reference
string
memo
string

the transfer memo for a payment sent by hand (the reference)

expires_at
string (date-time)
network_name
string

the resolved network name, as stored

network_id
string (uuid)
error
object
message
string
POST/pay/data/solana-statusPublicPay Data Solana Status

The state of a data pack payment started with /pay/data/solana-intent, for the buy-data page to poll while it waits: pending until the USDC transfer is credited, paid once the data is on the network, expired when the intent passed expires_at unpaid, unknown for a reference that is not a data pack intent (plan intents made by a signed-in wallet are not reported here). Unauthenticated, per-ip rate limited.

Request bodyshow schema
reference
string
Responses1 status · show schema
200
status
string
enum: pending, paid, expired, unknown
item_id
string
enum: data_1tib, data_10tib
network_name
string
amount_usd
number
expires_at
string (date-time)
POST/stripe/create-checkout-sessionBearer authStripe Create Checkout Session

Create a Stripe Checkout Session for a subscription or data pack.

ui_mode selects which shape the result carries -- a single Stripe session cannot produce both:

  • "hosted" (the default, so existing callers are unchanged): returns checkout_url, which the client opens in a browser. - "embedded": returns client_secret and publishable_key, which the client uses to mount Stripe Embedded Checkout inline (the desktop apps load ur.io/checkout in a webview with these).

The subscription is granted by the invoice.paid webhook, never by the client; the client only polls /subscription/balance afterwards.

Request bodyshow schema
item_id
string
storefront_country
string

ISO 3166-1 storefront country, when the caller knows it. The Pro items are priced at the caller's regional tier and, when the welcome offer is redeemable (yearly only), the 25% coupon is applied server-side; the charged tier is finalized from the card's billing country once attached.

ui_mode
string

"hosted" (default) or "embedded".

enum: hosted, embedded
Responses1 status · show schema
200
ui_mode
string

which of the two shapes below is populated

checkout_url
string

hosted mode only

client_secret
string

embedded mode only

publishable_key
string

embedded mode only

session_id
string

both modes; the caller can reconcile the purchase with this

error
object
message
string
POST/verifyPublicVerify

One step of the validator's routing-verification protocol. The route accepts two body shapes:

  • SEED starts a new trail through the validator-chosen entry provider.
  • EXTEND claims the pending assigned hop of an active trail.

The request must egress from the provider being claimed - the server resolves the hop from the request source IP, never from the body. Authentication is the protocol's own Ed25519 signatures (over the canonical binary messages, not the JSON), not a JWT. A non-final step returns the assign result (the server's signed commitment to the next hop); the final step returns status "complete" and the published proof.

Request bodyshow schema
one of
client_id
string

uuid. The validator's own client_id; the server checks vpk equals this client's registered Ed25519 key.

vpk
string

base64 encoded 32-byte Ed25519 validator path key.

client_nonce
string

base64 encoded 32-byte nonce.

seed_sig
string

base64 encoded 64-byte Ed25519 SEED signature.

M
integer

Requested trail depth. The server clamps to its allowed range.

client_id
string

uuid. The validator's own client_id.

trail_id
string

uuid

trail
array<string>

The ordered confirmed hop client_ids plus the single pending hop being claimed.

array
string

uuid

extend_sig
string

base64 encoded 64-byte Ed25519 EXTEND signature.

Responses1 status · show schema
200
one of
trail_id
string

uuid

server_nonce
string

base64 encoded 32-byte per-trail server nonce.

trail
array<string>

The ordered confirmed hop client_ids (ids only; times are published only in the final proof).

array
string

uuid

next_hop
string

uuid. The newly assigned pending hop.

M
integer

The server-clamped effective trail depth.

server_key_id
integer

1-byte id of the server key that signed assign_sig. See /verify/keys.

assign_sig
string

base64 encoded 64-byte Ed25519 ASSIGN signature by the server (msg_type 0x03).

status
string

"complete"

proof
VerifyProof
header
VerifyProofHeader
trail_id
string

uuid

server_nonce
string

base64 encoded 32-byte per-trail server nonce.

vpk
string

base64 encoded 32-byte Ed25519 validator path key.

M
integer

Trail depth.

hops
array<VerifyProofHop>
array
client_id
string

uuid. The canonical provider at this hop.

time_ms
integer

Server-stamped confirmation time, unix milliseconds UTC.

egress_ip_hash
array<integer>

The 32-byte hash of the provider's egress IP at the subnet's configured prefix granularity. Marshals on the wire as a JSON array of 32 integers (a Go [32]byte), not a base64 string.

array
integer
server_key_id
integer

1-byte id of the server key that signed final_sig.

coverage
integer

The server-attested coverage of the trail (v1 = M-1, the server-assigned confirmed hops with the seed excluded).

final_sig
string

base64 encoded 64-byte Ed25519 FINAL signature by the server.

verifier_sig
string

base64 encoded 64-byte Ed25519 depth-M EXTEND signature by the validator.

GET/verify/keysPublicVerify Keys

The published server Ed25519 verify keys, by serverkeyid. All historical keys are listed so old proofs remain verifiable across key rotations.

Responses1 status · show schema
200
keys
array<VerifyServerKey>
array
server_key_id
integer

1-byte key rotation id.

public_key
string

base64 encoded 32-byte Ed25519 public key.

GET/sn/walletBearer authSn Get Wallet

The coldkeys attached inside the caller's network: the network-level wallet (no client_id) and every provider client's wallet. wallet is the session's effective wallet (the client-scoped wallet for a client session when set, else the network wallet); absent when none is attached. An empty wallets list is not an error.

Responses1 status · show schema
200
wallet
SnWallet
coldkey_ss58
string
client_id
string

uuid of the provider client; absent for the network-level wallet.

set_at_millis
integer

Unix time in milliseconds the wallet was set.

wallets
array<SnWallet>
array
coldkey_ss58
string
client_id
string

uuid of the provider client; absent for the network-level wallet.

set_at_millis
integer

Unix time in milliseconds the wallet was set.

error
object
message
string
POST/sn/walletBearer authSn Set Wallet

Attach the caller's subnet coldkey - the ss58 address that pool payouts are claimable by. Proof of key possession is required: message is the single-use challenge issued by POST /auth/wallet-challenge for blockchain TAO and signature is the coldkey's sr25519 signature over it. client_id scopes the wallet to one provider client (a client-scoped JWT selects its own client). Banned addresses are rejected. Not retroactive: the wallet applies from the next committed epoch's leaf set. This wallet is deliberately separate from the account payout wallet.

Request bodyshow schema
coldkey_ss58
string

The subnet coldkey as an ss58 address (Bittensor prefix 42).

client_id
string

uuid of the provider client the wallet is attached to. Defaults to the session client for a client-scoped JWT; must belong to the caller's network.

signature
string

The coldkey's sr25519 signature (hex) over message. Required for app callers.

message
string

The exact single-use challenge text issued by POST /auth/wallet-challenge for blockchain TAO and this address.

Responses1 status · show schema
200
error
object
message
string
POST/sn/wallet/validatePublicSn Validate Wallet

Checks an address before it is attached: ss58 syntax with the Bittensor prefix, the operator ban list, and whether the account exists on the subtensor chain. When the chain cannot be reached the result reports exists_on_chain: true with a message, so an outage never blocks a user. No authentication; chain lookups are rate limited per source address.

Request bodyshow schema
address
string

The ss58 address to check.

Responses1 status · show schema
200
valid_syntax
boolean

The address decodes as ss58 with the Bittensor prefix.

exists_on_chain
boolean

The account exists on the subtensor chain (true when the chain could not be reached; see message).

banned
boolean

The address is on the operator ban list and must not be attached.

message
string
GET/sn/headBearer authSn Head

The caller network's standing for a head mining spot (Top 200, WHITEPAPER 8.4). score is the server's estimate of split-adjusted distinct routable egress-IP breadth from the live trail egress index, floor the score of the last network inside cutoff (0 while fewer networks score), rank_estimate 1-based (0 without a score). bound/hotkey/uid reflect an active head binding. source is "server" until validators publish consensus scores on chain; a chain outage degrades to the estimate, never an error.

Responses1 status · show schema
200
eligible
boolean

The estimate places the network inside the cutoff.

score
number (double)

Split-adjusted distinct routable egress-IP breadth (server estimate).

floor
number (double)

Score of the last network inside the cutoff; 0 while fewer networks score.

rank_estimate
integer

1-based estimated rank; 0 without a score.

cutoff
integer

Head-tier size (200).

bound
boolean

An active head binding exists for one of the network's clients.

hotkey
string

The bound head hotkey as ss58; absent when not bound.

uid
integer

The bound uid; 0 when not bound.

rank
integer

The bound network's estimated rank; 0 when not bound.

epoch
integer

The current contract epoch.

netuid
integer
source
string

"server" (estimate) or "chain" (validator consensus).

error
object
message
string
POST/sn/head/bindingBearer authSn Head Binding

Store a device's consent for a fleet binding (WHITEPAPER 11.4): the canonical binding payload and the client's Ed25519 signature over its keccak256 digest, optionally with the head hotkey's sr25519 signature. When both signatures verify the response carries the bindFleetMember calldata for the operator to submit from their own key. The server never submits on chain.

Request bodyshow schema
binding
SnFleetBinding
chain_id
integer
netuid
integer
coordinator
string

0x-hex coordinator contract address.

fleet_id
string
hotkey
string
client_id
string

uuid

client_key
string

0x-hex 32-byte client Ed25519 public key.

generation
integer
valid_from_epoch
integer
valid_to_epoch
integer
commitment_hash
string
client_signature
string

The device's Ed25519 signature (hex) over the binding digest; signature is accepted as an alias.

signature
string
hotkey_signature
string

The head hotkey's sr25519 signature (hex) over the same digest; optional, required for calldata.

hotkey
string

Optional override of the binding's hotkey (ss58 or 0x-hex).

Responses1 status · show schema
200
digest
string

0x-hex keccak256 binding digest.

client_signature_valid
boolean
hotkey_signature_valid
boolean
ready
boolean

Both signatures verified and calldata is present.

calldata
string

0x-hex bindFleetMember calldata for the operator to submit.

to
string

The coordinator contract address to send the calldata to.

data
string

Same as calldata.

contract_address
string
chain_id
integer
error
object
message
string
GET/sn/pool/claimBearer authSn Pool Claim

The caller network's merkle pool-payout claim for an epoch: everything needed to call claim on the subnet contract. Claims are served once the epoch is finalized on chain.

Parameters
epoch(query)
integer

Epoch index

required
Responses1 status · show schema
200
epoch
integer

Epoch index.

no_id
string

base64 encoded 32-byte network operator id, as committed on chain.

coldkey
string

base64 encoded 32-byte coldkey public key (the ss58-decoded key set via /sn/wallet).

share_bps
integer

The caller's payout share in basis points.

proof
array<string>

Merkle proof from the (noid, coldkey, sharebps) leaf to payout_root.

array
string

base64 encoded 32-byte node hash.

payout_root
string

base64 encoded 32-byte committed payout merkle root.

contract_address
string

0x-hex EVM address of the subnet contract.

chain_id
integer

EVM chain id of the subnet contract chain.

claim_open_block
integer

Block number claims open at.

error
object
message
string
GET/sn/epochPublicSn Epoch

The current subnet epoch index, boundaries, and deadlines mirrored from chain, so clients do not need their own RPC.

Responses1 status · show schema
200
epoch
integer

Epoch index.

start_block
integer
commit_deadline_block
integer
trails_deadline_block
integer
finalize_block
integer
t_epoch_blocks
integer

Epoch length in blocks.

chain_id
integer

EVM chain id of the subnet contract chain.

contract_address
string

0x-hex EVM address of the subnet contract.

settlement_vault_address
string

0x-hex EVM address of the settlement vault claims are sent to; absent when unset.

no_id
string

The operator id (decimal string); absent when unset.

netuid
integer
rpc_url
string

Public subtensor EVM JSON-RPC url for clients; absent when unset.

POST/onboarding/offer/issueBearer authonboardingOfferIssue

Issue the caller's welcome offer: 25% off the first year of Pro (3 months free), valid validity_days (5) from issue, stacked on the 14-day trial, redeemable on every store. Issued ONCE per network: the call is idempotent and returns the existing offer in whatever state it is in (created: false); an expired offer is never re-issued. Call it the moment the offer surface renders (the intro plan step), so the deadline is real.

Refused with error when the onboarding config is absent, or when the caller is in the holdout variant of the in-app offer experiment (experiments["offer.in_app"]): those networks show the regular plan picker and reach the offer by email instead.

Budgeted per caller address (30 per 10 minutes): over budget the response is 429 with a Retry-After header.

Request bodyshow schema
surface
OfferSurface
string

Where the offer is shown.

enum: intro_step, final_screen, email_link, account
storefront_country
string

ISO 3166-1 storefront country, when the app knows it

Responses3 statuses · show schema
200
offer
one of

The offer; null when refused.

one of
issued_at
string (date-time)
expires_at
string (date-time)
percent_off
integer
months_free
integer
first_year_usd
number
regular_year_usd
number
tier
string
currency
string
state
string
enum: active, redeemed, expired
apple_offer_code
string
play_offer_tag
string
stripe_coupon_id
string
redeemed_at
one of

When the offer was first redeemed; null until then.

one of
string (date-time)
null
store
one of

The store of the first redemption; null until then.

one of
string
enum: apple, play, stripe, solana
null
null
created
boolean

true for the call that issued the offer

error
one of
one of
message
string
null
401
No body
429
error
object
message
string
retry_after_seconds
integer
POST/client/eventsBearer authclientEventsSend

Store a batch of product events (at most 200 per call) against the CLOSED event schema (see ClientEvent). The network id comes from the bearer token only; country_tier, path, experiment and variant are stamped by the server. Unknown event names, unknown prop keys, missing required props and ill-typed values are refused PER EVENT in rejected (the rest of the batch is stored); a rejection is final, the client must not resend that event. No free text is stored except feedback.submitted.text, which is redacted (emails, phone numbers, IP addresses) before storage.

Clients batch every 30 s or on background, drop an event after three failed calls, and never send more than 200 per call (a larger batch is a 400). Budgeted per caller address (120 calls per 10 minutes): over budget the response is 429 with a Retry-After header.

Request bodyshow schema
events
array<ClientEvent>
array
one of
ClientEventBase (recursive)
name
string
props
object
step
EventToken
EventToken (recursive)
index
integer
elapsed_ms
integer
ClientEventBase (recursive)
name
string
props
object
step
EventToken
EventToken (recursive)
index
integer
elapsed_ms
integer
ClientEventBase (recursive)
name
string
props
object
step
EventToken
EventToken (recursive)
index
integer
elapsed_ms
integer
ClientEventBase (recursive)
name
string
props
object
surface
OfferSurface
OfferSurface (recursive)
experiment
EventToken
EventToken (recursive)
variant
EventToken
EventToken (recursive)
tier
PriceTierName
PriceTierName (recursive)
price_shown
number
currency
CurrencyCode
CurrencyCode (recursive)
expires_in_s
integer
ClientEventBase (recursive)
name
string
props
object
plan
OfferPlan
OfferPlan (recursive)
ClientEventBase (recursive)
name
string
props
object
plan
OfferPlan
OfferPlan (recursive)
store
EventStore
EventStore (recursive)
ClientEventBase (recursive)
name
string
props
object
control
OfferDeclineControl
OfferDeclineControl (recursive)
elapsed_ms
integer
ClientEventBase (recursive)
name
string
props
object
store
EventStore
EventStore (recursive)
product
EventToken
EventToken (recursive)
plan
OfferPlan
OfferPlan (recursive)
trial
boolean
price
number
currency
CurrencyCode
CurrencyCode (recursive)
ClientEventBase (recursive)
name
string
props
object
store
EventStore
EventStore (recursive)
product
EventToken
EventToken (recursive)
plan
OfferPlan
OfferPlan (recursive)
trial
boolean
price
number
currency
CurrencyCode
CurrencyCode (recursive)
ClientEventBase (recursive)
name
string
props
object
store
EventStore
EventStore (recursive)
product
EventToken
EventToken (recursive)
plan
OfferPlan
OfferPlan (recursive)
trial
boolean
price
number
currency
CurrencyCode
CurrencyCode (recursive)
ClientEventBase (recursive)
name
string
props
object
store
EventStore
EventStore (recursive)
product
EventToken
EventToken (recursive)
plan
OfferPlan
OfferPlan (recursive)
trial
boolean
price
number
currency
CurrencyCode
CurrencyCode (recursive)
error_class
EventToken
EventToken (recursive)
ClientEventBase (recursive)
name
string
props
object
empty object
ClientEventBase (recursive)
name
string
props
object
kind
EventToken
EventToken (recursive)
ClientEventBase (recursive)
name
string
props
object
rating
integer
reason
EventToken
EventToken (recursive)
has_text
boolean
text
string

free text, redacted (emails, phone numbers, IP addresses) before storage

ClientEventBase (recursive)
name
string
props
object
product_updates
boolean
Responses4 statuses · show schema
200
accepted
integer

events stored (or deduplicated)

rejected
array<object>

schema refusals by batch index; final, do not resend

array
index
integer
message
string
400
No body
401
No body
429
error
object
message
string
retry_after_seconds
integer
POST/onboarding/clickPubliconboardingClick

Record a campaign landing-page click. Every onboarding email link is https://ur.io/o/?t=; the landing page posts the token here, which writes the server-side landing.clicked attribution event and answers with the in-app destination to route to (onboarding/connect, onboarding/widgets, onboarding/offer, onboarding/feedback). An app open (/network/auth-client) within 48 h of the click is attributed to it as app.opened.

No authentication: the signed token is the credential, and the response carries nothing about the network. An expired token still returns step and destination (with ok: false, error: expired) so the page can route without attributing; an invalid token returns ok: false, error: invalid. Budgeted per caller address (60 per 10 minutes) -> 429 with Retry-After.

Request bodyshow schema
token
string
Responses2 statuses · show schema
200
ok
boolean
step
string

the campaign step the link belongs to (e.g. e1_connect)

destination
string

the in-app destination to route to

enum: onboarding/connect, onboarding/widgets, onboarding/offer, onboarding/feedback
error
string
enum: invalid, expired
429
error
object
message
string
retry_after_seconds
integer
GET/onboarding/feedback/{token}PubliconboardingFeedbackToken

Resolve a feedback link token (https://ur.io/f/?r=n or ?why=n) to the rating or reason the one-tap email button stood for, so the in-app feedback screen opens pre-filled. The token carries the step and may carry the rating/reason; r (1-5) and why (a reason token) override when present. The app then submits the actual feedback through /feedback/send-feedback and reports feedback.submitted through /client/events.

No authentication: the signed token is the credential. Budgeted per caller address (60 per 10 minutes) -> 429 with Retry-After.

Parameters
token(path)
string

The signed feedback token from the email link.

required
r(query)
integer

Rating 1-5 from the tapped button.

why(query)
string

Reason token from the tapped button.

Responses2 statuses · show schema
200
ok
boolean
step
string
rating
integer

1-5, 0 when the link carried none

reason
string
error
string
enum: invalid, expired
429
error
object
message
string
retry_after_seconds
integer
GET/admin/onboarding/resultsBearer authadminOnboardingResults

The nightly aggregate the analysis script (mmm/onboarding/analyze.mjs) reads: onboarding_results_daily, recomputed at 02:00 UTC by the OnboardingResultsRollup task for the last onboarding.results.rollup_days cohort days (config/main/onboarding.yml). One row per cohort day (the network's sign-up day, UTC), experiment, variant, surface, platform, price tier and path. Counts are networks, never events.

Exposure is the registry assignment (hash of network id and experiment id), so holdout rows exist without any stamped event; for the email sequence it is the variant the campaign row was served, and only networks with an email address are exposed to an email experiment. The pseudo-experiment _all (variant all, surface all) counts every network of the cohort so the funnel per platform, tier and path is readable without an experiment. The cohort is the campaign's real population: a network enters (its cohort time is the enrollment time) when its login is an email address, otherwise on its first device client within 30 days of creation; a network with neither an email login nor a device is never a cohort member.

Column definitions, measured from each network's cohort time: sent, delivered, opened, clicked, unsubscribe, complaint = at least one email.* event of that name, any step; landing_clicked = a landing.clicked; app_open_48h = an app.opened (the auth-client attribution within 48 h of a landing click); connect_7d = a connect.day (server-written on each UTC day the network had a connection) or a connect.first within 7 days; widget_7d = widget.added within 7 days; feedback_7d = feedback.submitted or an account feedback within 7 days; pro_start_14d = a purchase.completed or the first subscription renewal (trial included) within 14 days; trial_to_paid_35d = trial.converted within 35 days; refund_60d = a refund within 60 days; retention_d7 = a connect.day on day 6 or 7; retention_d30 = a connect.day on day 28, 29 or 30. Connection days are the analytics events, never the connection table (which is pruned hours after disconnect), so they exist from the day the server started writing connect.day. A window that has not matured reports 0: read matured_days (the cohort's age at computed_at) to tell "not yet" from "did not".

Volume floor: rows with fewer than onboarding.results.min_exposures exposures (default 10) are suppressed, and no identifier of any kind is returned. Ordered by the dimension tuple; keyset paged by cursor.

Auth: Authorization: Bearer where the token is listed in vault onboarding.yml under onboarding.admin_bearers (compared in constant time). A missing or unknown token is 401; a network JWT is

  1. Without the vault entry the endpoint is closed.
Parameters
experiment(query)
string

The experiment id from the registry.

required
from(query)
string (date)

First cohort day, inclusive (YYYY-MM-DD).

required
to(query)
string (date)

Last cohort day, inclusive (YYYY-MM-DD).

required
surface(query)
string
platform(query)
EventPlatform
tier(query)
PriceTierName
path(query)
string

The campaign path, A (saw the in-app offer) or B.

cursor(query)
string

The next_cursor of the previous page.

limit(query)
integer

Rows per page, 1-1000 (default 500).

Responses4 statuses · show schema
200
rows
array<OnboardingResultsRow>
array
cohort_day
string (date)
experiment
string
variant
string
surface
string
platform
string

An EventPlatform, or unknown when the sign-up did not say.

tier
string

A PriceTierName, or unknown when the sign-up country is unknown.

path
string

The campaign path A or B, or unknown.

exposures
integer
sent
integer
delivered
integer
opened
integer
clicked
integer
landing_clicked
integer
app_open_48h
integer
connect_7d
integer
widget_7d
integer
feedback_7d
integer
pro_start_14d
integer
trial_to_paid_35d
integer
refund_60d
integer
retention_d7
integer
retention_d30
integer
unsubscribe
integer
complaint
integer
matured_days
integer

The cohort's age in whole days at computed_at; a window longer than this has not been measured yet.

computed_at
string (date-time)
next_cursor
stringnull

The cursor for the next page; null on the last page.

min_exposures
integer

The volume floor applied to this page.

400
No body
401
No body
403
No body
GET/admin/onboarding/experimentsBearer authadminOnboardingExperiments

The onboarding experiment registry (config/main/onboarding.yml onboarding.experiments) as the server loaded it, so the analysis script judges results against the same allocation, primary metric, guardrails and minimum exposures the server applied, plus each experiment's live variant states from the pause overlay (network_onboarding_experiment_state: a variant the nightly guardrail check or bringyourctl onboarding experiments --pause paused is served as control until resumed) and the results configuration (min_exposures, rollup_days, guardrail_days). Same auth as /admin/onboarding/results.

Responses3 statuses · show schema
200
experiments
array<OnboardingExperiment>
array
id
string
surface
string

email. | offer.in_app | offer.email | cadence

status
string
enum: draft, running, paused, done
start
string (date)
stop
string (date)
allocation
map

percent per variant name, by hash(network_id, id)

map
number
variants
map

per variant, the Brevo template name or the store copy key set and layout id

map
empty object
primary_metric
string
secondary
array<string>
array
string
guardrails
map
map
number
min_exposures
integer
active
boolean

Whether the experiment assigns right now (status running, within start/stop).

variant_states
array<OnboardingExperimentVariantState>

The pause overlay rows of this experiment (empty when nothing was ever paused).

array
experiment_id
string
variant
string
status
string

paused = served as control; running = resumed.

enum: paused, running
reason
string
updated_at
string (date-time)
results
object

The results configuration the rollup and the results endpoint apply.

min_exposures
integer
rollup_days
integer
guardrail_days
integer
401
No body
403
No body
POST/updates/brevoBearer authbrevoWebhook

The Brevo transactional-email webhook. Brevo is registered (idempotently, by the server when onboarding.enabled is on) to post one event per delivery step; the request is authenticated by a bearer token from the account's webhook_bearers list, not by a network token. unsubscribe turns the account's product-updates preference off (the existing behavior); for the onboarding campaign the remaining events are recorded as server-written email.delivered|opened|clicked|bounced|complained|unsubscribed events against the network, with the campaign step taken from the message's tag (onboarding, , ) or the X-Mailin-custom header, so e1_connect clicks and e4b_offer complaints land on the right step. A hard bounce or a complaint exits the network from the sequence.

Request bodyshow schema
event
string
enum: request, delivered, opened, uniqueOpened, click, hardBounce, softBounce, blocked, spam, complaint, unsubscribed, unsubscribe, invalid, deferred, error
email
string
message-id
string
tags
array<string>

the send's tags; the campaign sends carry [onboarding, , ]

array
string
tag
string

Brevo's legacy form of the tags, a JSON-encoded array in a string

template_id
integer
X-Mailin-custom
string

the campaign sets this header to the step name on every send

link
string

the clicked URL (click events)

date
string
ts_event
integer

unix seconds of the event

Responses2 statuses · show schema
200
empty object
401
No body