‏API المشغّل • URnetwork

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

16 operations

POST/auth/loginPublicAuth Login

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

email
phone number
Apple JWT
Google JWT

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

The user's wallet address

wallet_message

string

The signed message

wallet_signature

string

blockchain

string

enum: solana

Responses1 status · show schema

200

user_name

string

user_auth

string

email or phone number

auth_allowed

array<string>

array

string

enum: password, apple, google

error

object

suggested_user_auth

string

enum: password, apple, google

message

string

network

object

by_jwt

string

wallet_auth

WalletAuthArgs

wallet_address

string

The user's wallet address

wallet_message

string

The signed message

wallet_signature

string

blockchain

string

enum: solana

Requestapplication/json

{
  "user_auth": "[email protected]",
  "auth_jwt": "string",
  "auth_jwt_type": "apple",
  "wallet_auth": {
    "wallet_address": "string",
    "wallet_message": "string",
    "wallet_signature": "string",
    "blockchain": "solana"
  }
}

Response200

{
  "user_name": "string",
  "user_auth": "[email protected]",
  "auth_allowed": [
    "password"
  ],
  "error": {
    "suggested_user_auth": "password",
    "message": "string"
  },
  "network": {
    "by_jwt": "string"
  },
  "wallet_auth": {
    "wallet_address": "string",
    "wallet_message": "string",
    "wallet_signature": "string",
    "blockchain": "solana"
  }
}

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

Requestapplication/json

{
  "user_auth": "[email protected]",
  "password": "string",
  "verify_otp_numeric": false
}

Response200

{
  "verification_required": {
    "user_auth": "[email protected]"
  },
  "network": {
    "by_jwt": "string",
    "name": "string"
  },
  "error": {
    "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-createPublicAuth Network Create

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

The user's wallet address

wallet_message

string

The signed message

wallet_signature

string

blockchain

string

enum: solana

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.

Responses1 status · 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

Requestapplication/json

{
  "user_name": "string",
  "user_auth": "[email protected]",
  "auth_jwt": "string",
  "auth_jwt_type": "apple",
  "password": "string",
  "network_name": "string",
  "terms": false,
  "verify_use_numeric": false,
  "wallet_auth": {
    "wallet_address": "string",
    "wallet_message": "string",
    "wallet_signature": "string",
    "blockchain": "solana"
  },
  "referral_code": "string",
  "balance_code": "string"
}

Response200

{
  "network": {
    "by_jwt": "string",
    "network_id": "00000000-0000-0000-0000-000000000000",
    "network_name": "string",
    "is_pro": false
  },
  "user_auth": "[email protected]",
  "is_pro": false,
  "verification_required": {
    "user_auth": "[email protected]"
  },
  "error": {
    "message": "string"
  }
}

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

Requestapplication/json

{
  "duration_minutes": 0,
  "uses": 0,
  "roles": [
    "string"
  ],
  "principal": "string"
}

Response200

{
  "auth_code": "string",
  "duration_minutes": 0,
  "uses": 0,
  "error": {
    "auth_code_limit_exceeded": false,
    "message": "string"
  }
}

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. 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

The user's wallet address

wallet_message

string

The signed message

wallet_signature

string

blockchain

string

enum: solana

Responses1 status · show schema

200

error

object

message

string

Requestapplication/json

{
  "user_auth": "[email protected]",
  "auth_jwt": "string",
  "auth_jwt_type": "apple",
  "password": "string",
  "wallet_auth": {
    "wallet_address": "string",
    "wallet_message": "string",
    "wallet_signature": "string",
    "blockchain": "solana"
  }
}

Response200

{
  "error": {
    "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

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

15 operations

POST/network/auth-clientBearer authAuth Network Client

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.

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

value

performance_profile

object

window_type

one of

Optional. The default is "quality"

one of

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)

Responses1 status · 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:

URL	Auth
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

Requestapplication/json

{
  "client_id": "00000000-0000-0000-0000-000000000000",
  "source_client_id": "00000000-0000-0000-0000-000000000000",
  "description": "string",
  "device_spec": "string",
  "roles": [
    "string"
  ],
  "principal": "string",
  "proxy_config": {
    "lock_caller_ip": false,
    "lock_ip_list": [
      "string"
    ],
    "https_require_auth": false,
    "enable_wg": false,
    "initial_device_state": {
      "country_code": "string",
      "location": {
        "connect_location_id": {
          "client_id": "00000000-0000-0000-0000-000000000000",
          "location_id": "00000000-0000-0000-0000-000000000000",
          "location_group_id": "00000000-0000-0000-0000-000000000000",
          "best_available": false
        },
        "name": "string",
        "location_type": "country"
      },
      "performance_profile": {
        "window_type": "quality",
        "window_size": {
          "window_size_min": 0,
          "window_size_min_p2p_only": 0,
          "window_size_max": 0,
          "window_size_hard_max": 0,
          "window_size_reconnect_scale": 0,
          "keep_healthiest_count": 0,
          "ulimit": 0
        }
      }
    }
  }
}

Response200

{
  "by_client_jwt": "string",
  "client_id": "00000000-0000-0000-0000-000000000000",
  "proxy_config_result": {
    "keepalive_seconds": 0,
    "change_id": 0,
    "create_time": "string",
    "proxy_id": "00000000-0000-0000-0000-000000000000",
    "client_id": "00000000-0000-0000-0000-000000000000",
    "api_base_url": "string",
    "block": "string",
    "api_port": 0,
    "http_proxy_url": "string",
    "https_proxy_url": "string",
    "socks_proxy_url": "string",
    "auth_token": "string",
    "instance_id": "00000000-0000-0000-0000-000000000000",
    "proxy_host": "string",
    "socks_proxy_port": 0,
    "http_proxy_port": 0,
    "https_proxy_port": 0,
    "wg_config": {
      "wg_proxy_port": 0,
      "client_private_key": "string",
      "client_public_key": "string",
      "client_ipv4": "string",
      "proxy_public_key": "string",
      "config": "string"
    }
  },
  "error": {
    "client_limit_exceeded": false,
    "message": "string"
  }
}

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 all clients on this network.

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

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

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'

Response200

{
  "clients": [
    {
      "client_id": "00000000-0000-0000-0000-000000000000",
      "source_client_id": "00000000-0000-0000-0000-000000000000",
      "device_id": "00000000-0000-0000-0000-000000000000",
      "network_id": "00000000-0000-0000-0000-000000000000",
      "description": "string",
      "device_name": "string",
      "device_spec": "string",
      "create_time": "string",
      "auth_time": "string",
      "roles": [
        "string"
      ],
      "principal": "string",
      "provide_mode": -1,
      "proxy_client": {
        "change_id": 0,
        "create_time": "string",
        "proxy_id": "00000000-0000-0000-0000-000000000000",
        "client_id": "00000000-0000-0000-0000-000000000000",
        "api_base_url": "string",
        "block": "string",
        "api_port": 0,
        "http_proxy_url": "string",
        "https_proxy_url": "string",
        "socks_proxy_url": "string",
        "auth_token": "string",
        "instance_id": "00000000-0000-0000-0000-000000000000",
        "proxy_host": "string",
        "socks_proxy_port": 0,
        "http_proxy_port": 0,
        "https_proxy_port": 0,
        "wg_config": {
          "wg_proxy_port": 0,
          "client_private_key": "string",
          "client_public_key": "string",
          "client_ipv4": "string",
          "proxy_public_key": "string",
          "config": "string"
        }
      },
      "resident": {
        "client_id": "00000000-0000-0000-0000-000000000000",
        "instance_id": "00000000-0000-0000-0000-000000000000",
        "resident_id": "00000000-0000-0000-0000-000000000000",
        "resident_host": "string",
        "resident_service": "string",
        "resident_block": "string",
        "resident_internal_ports": [
          0
        ]
      },
      "connections": [
        {
          "client_id": "00000000-0000-0000-0000-000000000000",
          "connection_id": "00000000-0000-0000-0000-000000000000",
          "connect_time": "string",
          "disconnect_time": "string",
          "connection_host": "string",
          "connection_service": "string",
          "connection_block": null
        }
      ]
    }
  ]
}

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

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

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

Response200

{
  "peers": [
    {
      "client_id": "00000000-0000-0000-0000-000000000000",
      "provide_modes": [
        -1
      ],
      "principal": "string",
      "roles": [
        "string"
      ],
      "device_name": "string",
      "device_spec": "string",
      "disconnect_time": "string"
    }
  ],
  "disconnected": [
    {
      "client_id": "00000000-0000-0000-0000-000000000000",
      "provide_modes": [
        -1
      ],
      "principal": "string",
      "roles": [
        "string"
      ],
      "device_name": "string",
      "device_spec": "string",
      "disconnect_time": "string"
    }
  ],
  "disconnected_count": 0,
  "error": {
    "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

Response200

{
  "groups": [
    {
      "location_group_id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "provider_count": 0,
      "promoted": false,
      "match_distance": 0
    }
  ],
  "locations": [
    {
      "location_id": "00000000-0000-0000-0000-000000000000",
      "location_type": "city",
      "name": "string",
      "city": "string",
      "city_location_id": "00000000-0000-0000-0000-000000000000",
      "region": "string",
      "region_location_id": "00000000-0000-0000-0000-000000000000",
      "country": "string",
      "country_location_id": "00000000-0000-0000-0000-000000000000",
      "country_code": "string",
      "provider_count": 0,
      "match_distance": 0,
      "stable": false,
      "strong_privacy": false
    }
  ],
  "devices": [
    {
      "client_id": "00000000-0000-0000-0000-000000000000",
      "device_name": "string"
    }
  ],
  "country_count": 0,
  "region_count": 0,
  "city_count": 0,
  "stable_count": 0,
  "strong_privacy_count": 0
}

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

Requestapplication/json

{
  "query": "string",
  "max_distance_fraction": 0,
  "enable_max_distance_fraction": false,
  "rank_mode": "string"
}

Response200

{
  "groups": [
    {
      "location_group_id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "provider_count": 0,
      "promoted": false,
      "match_distance": 0
    }
  ],
  "locations": [
    {
      "location_id": "00000000-0000-0000-0000-000000000000",
      "location_type": "city",
      "name": "string",
      "city": "string",
      "city_location_id": "00000000-0000-0000-0000-000000000000",
      "region": "string",
      "region_location_id": "00000000-0000-0000-0000-000000000000",
      "country": "string",
      "country_location_id": "00000000-0000-0000-0000-000000000000",
      "country_code": "string",
      "provider_count": 0,
      "match_distance": 0,
      "stable": false,
      "strong_privacy": false
    }
  ],
  "devices": [
    {
      "client_id": "00000000-0000-0000-0000-000000000000",
      "device_name": "string"
    }
  ],
  "country_count": 0,
  "region_count": 0,
  "city_count": 0,
  "stable_count": 0,
  "strong_privacy_count": 0
}

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

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

Requestapplication/json

{
  "specs": [
    {
      "location_id": "00000000-0000-0000-0000-000000000000",
      "location_group_id": "00000000-0000-0000-0000-000000000000",
      "client_id": "00000000-0000-0000-0000-000000000000",
      "best_available": false
    }
  ],
  "count": 0,
  "force_count": false,
  "exclude_client_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "exclude_destinations": [
    [
      "00000000-0000-0000-0000-000000000000"
    ]
  ],
  "rank_mode": "quality",
  "force_minimum": false
}

Response200

{
  "providers": [
    {
      "client_id": "00000000-0000-0000-0000-000000000000",
      "estimated_bytes_per_second": 0,
      "has_estimated_bytes_per_second": false,
      "tier": 0,
      "intermediary_ids": [
        "00000000-0000-0000-0000-000000000000"
      ],
      "location": {
        "country": "string",
        "country_code": "string",
        "region": "string",
        "city": "string",
        "country_location_id": "00000000-0000-0000-0000-000000000000",
        "region_location_id": "00000000-0000-0000-0000-000000000000",
        "city_location_id": "00000000-0000-0000-0000-000000000000",
        "region_coordinates": {
          "lat": 0,
          "lon": 0
        },
        "city_coordinates": {
          "lat": 0,
          "lon": 0
        }
      }
    }
  ]
}

GET/network/rankingBearer authNetwork Get Ranking

Get leaderboard ranking of current network

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

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/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

Response200

{
  "blocked_locations": [
    {
      "location_id": "00000000-0000-0000-0000-000000000000",
      "location_name": "string",
      "location_type": "string",
      "country_code": "string"
    }
  ],
  "error": {
    "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

Response200

{
  "reliability_window": {
    "mean_reliability_weight": 0,
    "min_time_unix_milli": 0,
    "min_bucket_number": 0,
    "max_time_unix_milli": 0,
    "max_bucket_number": 0,
    "bucket_duration_seconds": 0,
    "max_client_count": 0,
    "max_total_client_count": 0,
    "reliability_weights": [
      0
    ],
    "client_counts": [
      0
    ],
    "total_client_counts": [
      0
    ],
    "country_multipliers": [
      {
        "country_location_id": "00000000-0000-0000-0000-000000000000",
        "country": "string",
        "country_code": "string",
        "reliability_multiplier": 0
      }
    ]
  },
  "error": {
    "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

Response200

{
  "network_user": {
    "user_id": "00000000-0000-0000-0000-000000000000",
    "user_auth": "[email protected]",
    "verified": false,
    "auth_type": "string",
    "network_name": "string",
    "wallet_address": "string",
    "user_auths": [
      {
        "user_auth": "string",
        "auth_type": "string"
      }
    ],
    "sso_auths": [
      {
        "user_id": "00000000-0000-0000-0000-000000000000",
        "auth_type": "string",
        "auth_jwt": "string",
        "user_auth": "string"
      }
    ],
    "wallet_auths": [
      {
        "user_id": "00000000-0000-0000-0000-000000000000",
        "wallet_address": "string",
        "blockchain": "string"
      }
    ]
  },
  "error": {
    "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

6 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

Response200

{
  "lookback": 0,
  "created_time": 0,
  "all_transfer_data": {
    "<key>": 0
  },
  "all_transfer_summary": 0,
  "all_transfer_summary_rate": 0,
  "providers_data": {
    "<key>": 0
  },
  "providers_summary": 0,
  "countries_data": {
    "<key>": 0
  },
  "countries_summary": 0,
  "regions_data": {
    "<key>": 0
  },
  "regions_summary": 0,
  "cities_data": {
    "<key>": 0
  },
  "cities_summary": 0,
  "networks_data": {
    "<key>": 0
  },
  "networks_summary": 0,
  "devices_data": {
    "<key>": 0
  },
  "devices_summary": 0
}

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

Response200

{
  "created_time": "string",
  "providers": [
    {
      "client_id": "00000000-0000-0000-0000-000000000000",
      "connected": false,
      "connected_events_last_24h": [
        {
          "event_time": "string",
          "connected": false
        }
      ],
      "uptime_last_24h": 0,
      "transfer_data_last_24h": 0,
      "payout_last_24h": 0,
      "search_interest_last_24h": 0,
      "contracts_last_24h": 0,
      "clients_last_24h": 0
    }
  ]
}

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

Requestapplication/json

{
  "last_n": 0
}

Response200

{
  "created_time": "string",
  "providers": [
    {
      "client_id": "00000000-0000-0000-0000-000000000000",
      "connected": false,
      "connected_events_last_24h": [
        {
          "event_time": "string",
          "connected": false
        }
      ],
      "uptime_last_24h": 0,
      "transfer_data_last_24h": 0,
      "payout_last_24h": 0,
      "search_interest_last_24h": 0,
      "contracts_last_24h": 0,
      "clients_last_24h": 0
    }
  ]
}

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

Requestapplication/json

{
  "client_id": "00000000-0000-0000-0000-000000000000",
  "last_n": 0
}

Response200

{
  "lookback": 0,
  "created_time": "string",
  "uptime": {
    "<key>": 0
  },
  "transfer_data": {
    "<key>": 0
  },
  "payout": {
    "<key>": 0
  },
  "search_interest": {
    "<key>": 0
  },
  "contracts": {
    "<key>": 0
  },
  "clients": {
    "<key>": 0
  },
  "client_details": [
    {
      "client_id": "00000000-0000-0000-0000-000000000000",
      "transfer_data": {
        "<key>": 0
      }
    }
  ]
}

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

Requestapplication/json

{
  "last_n": 0
}

Response200

{
  "lookback": 0,
  "created_time": "string",
  "uptime": {
    "<key>": 0
  },
  "transfer_data": {
    "<key>": 0
  },
  "payout": {
    "<key>": 0
  },
  "search_interest": {
    "<key>": 0
  },
  "contracts": {
    "<key>": 0
  },
  "clients": {
    "<key>": 0
  }
}

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

error

object

message

string

Requestapplication/json

{}

Response200

{
  "earners": [
    {
      "network_id": "00000000-0000-0000-0000-000000000000",
      "network_name": "string",
      "net_mib_count": 0,
      "is_public": false,
      "contains_profanity": false
    }
  ],
  "error": {
    "message": "string"
  }
}

Subscription

4 operations

GET/subscription/balanceBearer authSubscription Balance

Get the current subscription status and transfer balance.

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

Response200

{
  "start_balance_byte_count": 0,
  "balance_byte_count": 0,
  "open_transfer_byte_count": 0,
  "current_subscription": {
    "subscription_id": "00000000-0000-0000-0000-000000000000",
    "store": "string",
    "plan": "string"
  },
  "active_transfer_balances": [
    {
      "balance_id": "00000000-0000-0000-0000-000000000000",
      "network_id": "00000000-0000-0000-0000-000000000000",
      "start_time": "string",
      "end_time": "string",
      "start_balance_byte_count": 0,
      "net_revenue_nano_cents": 0,
      "subsidy_net_revenue_nano_cents": 0,
      "balance_byte_count": 0,
      "purchase_token": "string",
      "paid": false
    }
  ],
  "pending_payout_usd_nano_cents": 0,
  "update_time": "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

Requestapplication/json

{
  "secret": "string"
}

Response200

{
  "balance": {
    "start_time": "string",
    "end_time": "string",
    "balance_byte_count": 0
  },
  "error": {
    "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

Requestapplication/json

{
  "secret": "string"
}

Response200

{
  "transfer_balance": {
    "transfer_balance_id": "00000000-0000-0000-0000-000000000000",
    "start_time": "string",
    "end_time": "string",
    "balance_byte_count": 0
  },
  "error": {
    "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

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

Response200

{
  "wallet_info": {
    "wallet_id": "string",
    "token_id": "string",
    "blockchain": "string",
    "blockchain_symbol": "string",
    "create_date": "string",
    "balance_usdc_nano_cents": 0,
    "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

Requestapplication/json

{
  "to_address": "string",
  "amount_usdc_nano_cents": 0,
  "terms": false
}

Response200

{
  "user_token": {
    "user_token": "string",
    "encryption_key": "string"
  },
  "challenge_id": "string",
  "error": {
    "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

Requestapplication/json

{
  "code": "string"
}

Response200

{
  "code_type": "share",
  "code": "string",
  "device_name": "string",
  "associated_network_name": "string",
  "client_id": "00000000-0000-0000-0000-000000000000",
  "duration_minutes": 0,
  "error": {
    "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

Requestapplication/json

{
  "device_name": "string",
  "device_spec": "string"
}

Response200

{
  "adopt_code": "string",
  "adopt_secret": "string",
  "duration_minutes": 0,
  "error": {
    "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

Requestapplication/json

{
  "adopt_code": "string",
  "adopt_secret": "string",
  "associated_network_name": "string"
}

Response200

{
  "by_client_jwt": "string",
  "error": {
    "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

Response200

{
  "pending_adoption_devices": [
    {
      "pending": false,
      "code": "string",
      "device_name": "string",
      "duration_minutes": 0
    }
  ],
  "incoming_shared_devices": [
    {
      "pending": false,
      "code": "string",
      "device_name": "string",
      "client_id": "00000000-0000-0000-0000-000000000000",
      "network_name": "string"
    }
  ],
  "outgoing_shared_devices": [
    {
      "pending": false,
      "code": "string",
      "device_name": "string",
      "client_id": "00000000-0000-0000-0000-000000000000",
      "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

18 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

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

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

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

Response200

{
  "network_points": [
    {
      "account_point_id": "00000000-0000-0000-0000-000000000000",
      "network_id": "00000000-0000-0000-0000-000000000000",
      "event": "referral",
      "point_value": 0,
      "payment_plan_id": "00000000-0000-0000-0000-000000000000",
      "account_payment_id": "00000000-0000-0000-0000-000000000000",
      "linked_network_id": "00000000-0000-0000-0000-000000000000",
      "create_time": "string"
    }
  ]
}

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

Response200

{
  "account_payments": [
    {
      "payment_id": "string",
      "payment_plan_id": "string",
      "wallet_id": "string",
      "network_id": "string",
      "payout_byte_count": 0,
      "payout_nano_cents": 0,
      "subsidy_payout_nano_cents": 0,
      "reliability_subsidy_nano_cents": 0,
      "min_sweep_time": "2026-01-01T00:00:00Z",
      "create_time": "2026-01-01T00:00:00Z",
      "payment_record": "string",
      "token_type": "string",
      "token_amount": 0,
      "payment_time": "2026-01-01T00:00:00Z",
      "payment_receipt": "string",
      "wallet_address": "string",
      "blockchain": "MATIC",
      "tx_hash": "string",
      "completed": false,
      "complete_time": "2026-01-01T00:00:00Z",
      "canceled": false,
      "cancel_time": "2026-01-01T00:00:00Z"
    }
  ],
  "error": {
    "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

Response200

{
  "wallets": [
    {
      "wallet_id": "00000000-0000-0000-0000-000000000000",
      "circle_wallet_id": "string",
      "network_id": "00000000-0000-0000-0000-000000000000",
      "wallet_type": "circle_uc",
      "blockchain": "SOL",
      "wallet_address": "string",
      "active": false,
      "default_token_type": "USDC",
      "create_time": "string",
      "has_seeker_token": false
    }
  ]
}

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

Response200

{
  "balance_codes": [
    {
      "balance_code_id": "00000000-0000-0000-0000-000000000000",
      "balance_byte_count": 0,
      "redeem_time": "string",
      "end_time": "string",
      "secret": "string"
    }
  ],
  "error": {
    "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

GET/account/referral-networkBearer authAccount Referral Network

Get the network that was referred the authenticated network

Responses1 status · show schema

200

network

ReferralNetwork

string

uuid

name

string

error

object

message

string

GET/account/unlink-referral-networkBearer authAccount Unlink Referral Network

Unlink the referral network from the authenticated network.

Responses1 status · show schema

200

empty object

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

Requestapplication/json

{
  "uses": {
    "personal": false,
    "business": false
  },
  "needs": {
    "private": false,
    "safe": false,
    "global": false,
    "collaborate": false,
    "app_control": false,
    "block_data_brokers": false,
    "block_ads": false,
    "focus": false,
    "connect_servers": false,
    "run_servers": false,
    "prevent_cyber": false,
    "audit": false,
    "zero_trust": false,
    "visualize": false,
    "other": "string"
  },
  "star_count": 0
}

Response200

{
  "feedback_id": "00000000-0000-0000-0000-000000000000"
}

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 authSolana Payment Intent

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

Responses1 status · show schema

200

error

object

message

string

Referral codes

1 operation

POST/referral-code/validateBearer authValidate Referral Code

Validate the referral code.

Request bodyshow schema

referral_code

string

Responses1 status · show schema

200

is_valid

boolean

is_capped

boolean

error

object

message

string

Other

12 operations

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

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

url

string

rtt

number

ws_url

string

coordinates

array<number>

array

number

connected_to_network

boolean

Response200

{
  "info": {
    "ip": "string",
    "location": {
      "coordinates": {
        "lat": 0,
        "lon": 0
      },
      "city": "string",
      "region": "string",
      "country": {
        "code": "string",
        "name": "string",
        "flag_url": "string"
      },
      "continent": {
        "code": "string",
        "name": "string"
      },
      "timezone": "string"
    },
    "privacy": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "relay": false,
      "hosting": false,
      "service": "string"
    }
  },
  "landmarks": [
    {
      "name": "string",
      "ip": "string",
      "url": "string",
      "rtt": 0,
      "ws_url": "string",
      "coordinates": [
        0
      ]
    }
  ],
  "connected_to_network": false
}

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

Requestapplication/json

{}

Response200

{
  "payment_intents": [
    {
      "subscription_type": "string",
      "client_secret": "string"
    }
  ],
  "ephemeral_key": "string",
  "customer_id": "string",
  "publishable_key": "string",
  "error": {
    "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/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

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

Requestapplication/json

{
  "item_id": "string",
  "ui_mode": "hosted"
}

Response200

{
  "ui_mode": "string",
  "checkout_url": "string",
  "client_secret": "string",
  "publishable_key": "string",
  "session_id": "string",
  "error": {
    "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.

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.

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.

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.

Requestapplication/json

{
  "client_id": "00000000-0000-0000-0000-000000000000",
  "vpk": "string",
  "client_nonce": "string",
  "seed_sig": "string",
  "M": 0
}

Response200

{
  "trail_id": "00000000-0000-0000-0000-000000000000",
  "server_nonce": "string",
  "trail": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "next_hop": "00000000-0000-0000-0000-000000000000",
  "M": 0,
  "server_key_id": 0,
  "assign_sig": "string"
}

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.

POST/sn/walletBearer authSn Set Wallet

Set the caller network's subnet coldkey - the ss58 address that pool payouts for this network are claimable by. This wallet is deliberately separate from the account payout wallet.

Request bodyshow schema

coldkey_ss58

string

The subnet coldkey as an ss58 address.

Responses1 status · show schema

200

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

Response200

{
  "epoch": 0,
  "no_id": "string",
  "coldkey": "string",
  "share_bps": 0,
  "proof": [
    "string"
  ],
  "payout_root": "string",
  "contract_address": "string",
  "chain_id": 0,
  "claim_open_block": 0,
  "error": {
    "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.

Response200

{
  "epoch": 0,
  "start_block": 0,
  "commit_deadline_block": 0,
  "trails_deadline_block": 0,
  "finalize_block": 0,
  "t_epoch_blocks": 0,
  "chain_id": 0,
  "contract_address": "string"
}