Wallets

Wallet endpoints support listing, registering external wallets, setting defaults, checking allowances, and sponsoring gas for eligible actions.

Capability execution resolves walletFlow from the selected wallet. A platform-managed wallet can use internal; a registered external wallet uses external and may require the client to sign or broadcast a returned payload. Do not send walletFlow yourself.

Prerequisites#

  • Dashboard API key
  • For mutations that sign or sponsor: session + WRITE permission on the key
  • Profile/team from onboard (wallets are often created during onboard)

List wallets#

Auth: API key. Query by profileId or teamId.

curl -sS "https://api-stg.vudy.app/v1/wallet/list?profileId=PROFILE_UUID" \
  -H "x-api-key: vudy_sandbox_YOUR_KEY"
const { data } = await fetch(
	`https://api-stg.vudy.app/v1/wallet/list?profileId=${profileId}`,
	{ headers: { "x-api-key": process.env.VUDY_API_KEY } },
).then((r) => r.json());
// { wallets, total } — list returns valid EVM wallets

Portfolio balances#

curl -sS "https://api-stg.vudy.app/v1/wallet/portfolio?wallets=0xABC...,0xDEF..." \
  -H "x-api-key: vudy_sandbox_YOUR_KEY"

Register an external wallet#

curl -sS https://api-stg.vudy.app/v1/wallet/external \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "TEAM_UUID",
    "profileId": "PROFILE_UUID",
    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "walletType": "EVM",
    "label": "Hot wallet"
  }'

walletType: EVM | SVM | BTC | FIAT.

Default wallet#

# Read
curl -sS "https://api-stg.vudy.app/v1/wallet/default?teamId=TEAM_UUID" \
  -H "x-api-key: vudy_sandbox_YOUR_KEY"

# Set
curl -sS -X POST "https://api-stg.vudy.app/v1/wallet/default?teamId=TEAM_UUID" \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"}'

Alias#

curl -sS -X PATCH https://api-stg.vudy.app/v1/wallet/alias \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "teamId": "TEAM_UUID",
    "alias": "Treasury"
  }'

Allowances and gas#

ActionAuthPath
Check allowanceAPI keyGET /v1/wallet/evm/allowance/{action}
ApproveSession + WRITEPOST /v1/wallet/evm/allowance/{action}
RevokeSession + WRITEDELETE /v1/wallet/evm/allowance/{action}
Check gas balanceAPI keyGET /v1/wallet/evm/check-gas-balance
Sponsor gasSession + WRITEPOST /v1/wallet/evm/gas-sponsor
# Check allowance for the send contract
curl -sS \
  "https://api-stg.vudy.app/v1/wallet/evm/allowance/send?chainId=1&userWallet=0xSENDER&tokenAddress=0xTOKEN&amount=50" \
  -H "x-api-key: vudy_sandbox_YOUR_KEY"

# Check whether the wallet has enough native gas
curl -sS \
  "https://api-stg.vudy.app/v1/wallet/evm/check-gas-balance?chainSlug=ethereum&wallet=0xSENDER&tokenAddress=0xTOKEN" \
  -H "x-api-key: vudy_sandbox_YOUR_KEY"

Approve and sponsor only when the preceding responses indicate they are needed:

await fetch("https://api-stg.vudy.app/v1/wallet/evm/allowance/send", {
	method: "POST",
	headers: {
		"x-api-key": process.env.VUDY_API_KEY,
		Authorization: `Bearer ${session}`,
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		chainId: "1",
		userWallet: senderAddress,
		tokenAddress,
		amount: 50,
	}),
});

await fetch("https://api-stg.vudy.app/v1/wallet/evm/gas-sponsor", {
	method: "POST",
	headers: {
		"x-api-key": process.env.VUDY_API_KEY,
		Authorization: `Bearer ${session}`,
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		walletAddress: senderAddress,
		action: "send",
		tokenAddress,
		chainSlug: "ethereum",
	}),
});

Use Wallets reference for exact query/body fields per action.

Next steps#