Account — API reference • URnetwork

POST/account/circle-walletPublicCircle Wallet Webhook

The Circle notification that a user-custody wallet challenge completed. Authenticated by the X-Circle-Signature ECDSA signature over the raw body under the key named by X-Circle-Key-Id, not by a URnetwork JWT. A challenges.initialize notification whose event is a completed INITIALIZE links the created wallet to the network named by the challenge's correlation id. Same handler as POST /pay/circle.

Request bodyshow schema

subscriptionId

string

notificationId

string

notificationType

string

notification

object

id

string

userId

string

status

string

correlationIds

array<string>

The first entry names the network the wallet belongs to.

array

string

errorCode

integer

type

string

timestamp

string (date-time)

version

integer

Responses1 status · show schema

200

empty object

Requestapplication/json

{
  "subscriptionId": "string",
  "notificationId": "string",
  "notificationType": "string",
  "notification": {
    "id": "string",
    "userId": "string",
    "status": "string",
    "correlationIds": [
      "string"
    ],
    "errorCode": 0,
    "type": "string"
  },
  "timestamp": "2026-01-01T00:00:00Z",
  "version": 0
}

Response200

{}

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. Claiming and changing have SEPARATE daily budgets: a first-time claim does not consume any of the rename budget, and vice versa. Renaming a name that is still inside its reclaim cooldown is charged to the change-name budget instead.

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

arraynull

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

stringnull

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

What earned the points. The server only writes the four payout events today; referral is historical, kept so rows written before the referral award was withdrawn still validate.

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

stringnull

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

stringnull

token_type

stringnull

token_amount

number,null (float)

payment_time

string,null (date-time)

payment_receipt

stringnull

wallet_address

stringnull

blockchain

string

enum: MATIC, SOL

tx_hash

stringnull

completed

boolean

complete_time

string,null (date-time)

canceled

boolean

cancel_time

string,null (date-time)

error

GetNetworkAccountPaymentsError

message

string

Response200

{
  "account_payments": [
    {
      "payment_id": "string",
      "payment_plan_id": "string",
      "wallet_id": null,
      "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": null,
      "token_type": null,
      "token_amount": null,
      "payment_time": null,
      "payment_receipt": null,
      "wallet_address": null,
      "blockchain": "MATIC",
      "tx_hash": null,
      "completed": false,
      "complete_time": null,
      "canceled": false,
      "cancel_time": null
    }
  ],
  "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

network_id

string

Ignored. The wallet is always created for the caller's own network, taken from the bearer token; this field is read off the body only to be overwritten.

blockchain

string

The blockchain associated with the address. SOL and MATIC are payout chains; TAO is accepted and stored as a non-payout identity. Case-insensitive.

enum: SOL, MATIC, TAO

wallet_address

string

The wallet address on blockchain

default_token_type

string

We only support "USDC"

enum: USDC

Responses1 status · show schema

200

wallet_id

string

udid

Requestapplication/json

{
  "network_id": "string",
  "blockchain": "SOL",
  "wallet_address": "string",
  "default_token_type": "USDC"
}

Response200

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

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

TAO appears for a wallet created as a non-payout identity.

enum: SOL, MATIC, TAO

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 or Saga Genesis token by validating a signed message. Either holding succeeds; a wallet with neither is refused with error.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

arraynull

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.

has_referral_network

boolean

True when this network is linked to a referrer and earns the referred bonus.

Response200

{
  "referral_code": "00000000-0000-0000-0000-000000000000",
  "total_referrals": 0,
  "max_referrals": 0,
  "bonus_per_referral_bytes": 0,
  "referred_bonus_bytes": 0,
  "bonus_period_seconds": 0,
  "has_referral_network": false
}

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

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