Utila Balances API
The Balances API from Utila — 5 operation(s) for balances.
OpenAPI Specification
openapi: 3.0.0
info:
title: Utila Address Book Balances API
version: v2
servers:
- url: https://api.utila.io
security:
- bearerAuth: []
tags:
- name: Balances
paths:
/v2/vaults/{vault_id}:queryBalances:
post:
summary: QueryBalances
description: Retrieve a list of all asset balances in all wallets in a vault.
operationId: Balances_QueryBalances
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2QueryBalancesResponse'
parameters:
- name: vault_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BalancesQueryBalancesBody'
required: true
tags:
- Balances
/v2/vaults/{vault_id}/wallets/{wallet_id}:queryBalances:
post:
summary: QueryWalletBalances
description: 'Retrieve a list of all asset balances in a wallet. Can be used also to retrieve assets across all wallets as per
[AIP-159](https://google.aip.dev/159) by using ''-'' (the hyphen or dash character) as a wildcard character instead of wallet ID in the parent.'
operationId: Balances_QueryWalletBalances
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2QueryWalletBalancesResponse'
parameters:
- name: vault_id
in: path
required: true
schema:
type: string
- name: wallet_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BalancesQueryWalletBalancesBody'
required: true
tags:
- Balances
/v2/vaults/{vault_id}/wallets/{wallet_id}/addresses/{address_id}:queryBalances:
post:
summary: QueryWalletAddressBalances
description: 'Retrieve a list of all asset balances in a wallet address. Can be used also to retrieve assets across all wallet adresses of a wallet as per
[AIP-159](https://google.aip.dev/159) by using ''-'' (the hyphen or dash character) as a wildcard character instead of wallet address ID in the parent.'
operationId: Balances_QueryWalletAddressBalances
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2QueryWalletAddressBalancesResponse'
parameters:
- name: vault_id
in: path
required: true
schema:
type: string
- name: wallet_id
in: path
required: true
schema:
type: string
- name: address_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BalancesQueryWalletAddressBalancesBody'
required: true
tags:
- Balances
/v2/vaults/{vault_id}:refreshAssetAddressBalance:
post:
summary: RefreshAssetAddressBalance
description: Refreshes address balance for given address.
operationId: Balances_RefreshAssetAddressBalance
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2RefreshAssetAddressBalanceResponse'
parameters:
- name: vault_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BalancesRefreshAssetAddressBalanceBody'
required: true
tags:
- Balances
/v2/vaults/{vault_id}/wallets/{wallet_id}:queryUTXOs:
post:
summary: QueryWalletUTXOs
description: Retrieve a list of all UTXOs in a wallet.
operationId: Balances_QueryWalletUTXOs
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2QueryWalletUTXOsResponse'
parameters:
- name: vault_id
in: path
required: true
schema:
type: string
- name: wallet_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BalancesQueryWalletUTXOsBody'
required: true
tags:
- Balances
components:
schemas:
v2DecodedAptosTransactionPayload:
type: object
properties:
entryFunction:
$ref: '#/components/schemas/v2DecodedAptosEntryFunction'
v2CantonTokenDetails:
type: object
properties:
instrumentId:
type: string
description: The instrument ID.
instrumentAdmin:
type: string
description: The instrument admin.
v2DecodedAptosEntryFunction:
type: object
properties:
function:
type: string
typeArguments:
type: array
items:
type: string
arguments:
type: array
items:
type: string
required:
- function
- typeArguments
- arguments
v2WalletTonDetails:
type: object
properties:
address:
type: string
description: The address of the wallet.
readOnly: true
BTCTransactionUTXOOut:
type: object
properties:
address:
description: Output address.
allOf:
- $ref: '#/components/schemas/apiv2Address'
amount:
type: string
description: Amount in asset unit (BTC).
change:
type: boolean
description: True when this output is the change output.
changeUserSelected:
type: boolean
description: 'True when the change address was supplied by the user; false when auto-generated.
Only meaningful when `change` is true.'
TransactionTonTransaction:
type: object
properties:
sender:
description: Ths source address of the transaction.
allOf:
- $ref: '#/components/schemas/apiv2Address'
seqno:
type: string
format: int64
description: The sequence number of the transaction.
messages:
type: array
items:
$ref: '#/components/schemas/TransactionTonTransactionMessage'
title: The messages posted to the blockchain
memo:
type: string
description: The memo of the transaction.
validUntil:
type: string
format: int64
description: The time the transaction is valid until.
amount:
type: string
description: The native amount passed to the transaction.
v2TronResourceFee:
type: object
properties:
consumed:
type: string
description: The amount of the resource consumed.
burned:
type: string
description: The amount of TRX burned for this resource.
convertedBurned:
description: The converted (fiat) value of the TRX burned for this resource.
allOf:
- $ref: '#/components/schemas/v2ConvertedValue'
description: Resource-level fee breakdown for a Tron resource (bandwidth or energy).
v2TransactionTonProof:
type: object
properties:
address:
type: string
description: 'The address of the signer.
In Raw address format.
Example: `0:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef`.'
appDomain:
type: string
title: The domain of the app requested the proof
payload:
type: string
description: The payload to sign.
timestamp:
type: string
format: int64
description: The time at which the signature was created.
signature:
type: string
description: The signature of the payload.
v2QueryWalletUTXOsResponse:
type: object
properties:
utxos:
type: array
items:
$ref: '#/components/schemas/apiv2UTXO'
description: The UTXOs returned.
nextPageToken:
type: string
description: 'A token, which can be sent as `pageToken` to retrieve the next page.
If this field is omitted, there are no subsequent pages.'
totalSize:
type: integer
format: int32
description: Total number of items in the response, regardless of pagination.
referencedResources:
type: object
additionalProperties:
$ref: '#/components/schemas/v2ReferencedResource'
description: 'A mapping of the referenced resources in the message.
The key is the resource name and the value is the corresponding resource.
This field is only populated if the `includeReferencedResources` field is set to `true`.'
v2AddressBookEntry:
type: object
properties:
name:
type: string
example: vaults/1b25635a5b3f/addressBookEntries/95257c5a522f
description: 'The resource name of the address book entry.
Format: `vaults/{vault_id}/addressBookEntries/{entry_id}`'
readOnly: true
address:
type: string
example: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6'
description: The blockchain address.
displayName:
type: string
example: My DeFi Wallet
description: A human-readable name for the address.
network:
type: string
example: networks/ethereum-mainnet
description: 'The resource name of the network this address belongs to.
Format: `networks/{network_id}`'
note:
type: string
example: This is my main trading wallet
description: Optional note attached to the address.
createTime:
type: string
format: date-time
example: '2023-01-15T10:30:00Z'
description: Output only. Creation time.
readOnly: true
tracked:
type: boolean
description: If true, assets of this address should be tracked by Utila.
associatedExternalWallet:
type: string
example: vaults/1b25635a5b3f/wallets/95257c5a522f
description: 'The wallet that is associated with this address.
Only set if `tracked` is true.
Format: `vaults/{vault_id}/wallets/{wallet_id}`'
readOnly: true
creator:
type: string
example: users/1b25635a5b3f/users/95257c5a522f
description: 'Output only. The user who issued the address book entry creation.
Format: `users/{user_id}`'
readOnly: true
signed:
type: boolean
description: 'Output only.
Whether the address book entry is cryptographically signed after going through the quorum approval process.'
readOnly: true
description: An address book entry.
required:
- address
- displayName
- network
DecodedCallArg:
type: object
properties:
name:
type: string
title: 'The name of the argument, for example: "dest"'
type:
type: string
title: 'The type of the argument, for example: "AccountId"'
value:
type: string
title: 'The value of the argument as a hex encoded byte array, for example: "0x1234"'
v2TransactionTronTransaction:
type: object
properties:
triggerSmartContract:
$ref: '#/components/schemas/v2TransactionTronTransactionTriggerSmartContract'
freezeBalanceV2:
$ref: '#/components/schemas/v2TransactionTronTransactionFreezeBalanceV2'
unfreezeBalanceV2:
$ref: '#/components/schemas/v2TransactionTronTransactionUnfreezeBalanceV2'
withdrawExpireUnfreeze:
$ref: '#/components/schemas/v2TransactionTronTransactionWithdrawExpireUnfreeze'
delegateResource:
$ref: '#/components/schemas/v2TransactionTronTransactionDelegateResource'
undelegateResource:
$ref: '#/components/schemas/v2TransactionTronTransactionUnDelegateResource'
cancelAllUnfreezeV2:
$ref: '#/components/schemas/v2TransactionTronTransactionCancelAllUnfreezeV2'
voteWitness:
$ref: '#/components/schemas/v2TransactionTronTransactionVoteWitness'
withdrawBalance:
$ref: '#/components/schemas/v2TransactionTronTransactionWithdrawBalance'
transferContract:
$ref: '#/components/schemas/TronTransactionTransferContract'
fee:
description: The fee details of the transaction.
allOf:
- $ref: '#/components/schemas/v2TronTransactionFee'
signature:
type: string
format: byte
description: "ECDSA signature (65 bytes) of the transaction.\n\nAvailable when the transaction has been signed.\n\nEncoded in standard TRON format:\n - Bytes [0-31]: R component (32 bytes, big-endian)\n - Bytes [32-63]: S component (32 bytes, big-endian)\n - Byte [64]: V component (recovery identifier)"
readOnly: true
apiv2Address:
type: object
properties:
value:
type: string
description: The actual address.
infoRef:
type: string
description: 'If it''s an address in the vault (e.g., a wallet address), a reference to address information will be listed here.
Address information can be fetched from `ReferencedAddressesInfo` map with the reference as the key.
Will be populated only if `includeReferencedResources` is set to `true`.'
apiUserStatusEnum:
type: string
enum:
- PENDING
- ACTIVE
WalletSolanaDetails:
type: object
properties:
address:
type: string
description: The address of the wallet.
readOnly: true
v2TransactionTronTransactionTriggerSmartContract:
type: object
properties:
ownerAddress:
description: 'The source of the transaction.
A base58 string address (example: `TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g`)'
allOf:
- $ref: '#/components/schemas/apiv2Address'
contractAddress:
description: 'The smart contract address.
A base58 string address (example: `TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g`)'
allOf:
- $ref: '#/components/schemas/apiv2Address'
callValue:
type: string
format: int64
description: 'The amount of SUN passed into the contract (1 TRX = 1,000,000 SUN).
Example: `500000`.'
data:
type: string
description: 'Hex encoded transaction data. This field will be returned only in FULL view.
Example: `0xa9059cbb0000000000000000000000002ed5dd8a98aea00ae32517742ea5289761b2710e0000000000000000000000000000000000000000000000000000000ba43b7400`.'
v2Transaction:
type: object
properties:
name:
type: string
example: vaults/1b25635a5b3f/transactions/95257c5a522f
description: 'The resource name of the transaction.
Format: `vaults/{vault_id}/transactions/{transaction_id}`.'
readOnly: true
type:
readOnly: true
allOf:
- $ref: '#/components/schemas/v2TransactionTypeEnum'
subType:
readOnly: true
allOf:
- $ref: '#/components/schemas/v2TransactionSubTypeEnum'
state:
readOnly: true
allOf:
- $ref: '#/components/schemas/v2TransactionStateEnum'
direction:
readOnly: true
allOf:
- $ref: '#/components/schemas/v2TransactionDirectionEnum'
note:
type: string
description: 'A note to attach to the transaction.
This note is visible to all vault members.'
network:
type: string
example: networks/ethereum-mainnet
description: 'The blockchain network on which the transaction was sent.
Not available for connection transactions (e.g., Exchanges)
Format: `networks/{network_id}`'
hash:
type: string
description: For on-chain transactions, the hash of the transaction.
blockNumber:
type: string
description: For on-chain transactions, the block number of the transaction if it was mined.
signingSession:
type: string
example: vaults/2d2e40r3/signingSessions/132e40r3
description: Available when the transaction has been prepared for signing / signed.
request:
description: The request details of the transaction. Relevant only for transactions initiated through Utila.
allOf:
- $ref: '#/components/schemas/v2TransactionRequest'
amlDetails:
readOnly: true
allOf:
- $ref: '#/components/schemas/TransactionAMLDetails'
gasStationOrder:
type: string
title: The gas station order name
readOnly: true
transfers:
type: array
items:
$ref: '#/components/schemas/TransactionTransfer'
description: If there one or more transfers in the transaction, they will be listed here.
tokenAllowances:
type: array
items:
$ref: '#/components/schemas/TransactionTokenAllowance'
description: If there one or more token allowances in the transaction, they will be listed here.
designatedSigners:
type: array
example:
- users/name@example.com
items:
type: string
description: 'If the transaction is designated to be signed by a specific signer, this field should be set.
Format: `users/{email}` or `users/{id}`
Example: `["users/name@example.com"]` or `["users/a3e4f5"]`'
evmTransaction:
description: 'For EVM-Compatible transaction: Low level transaction details.'
allOf:
- $ref: '#/components/schemas/v2TransactionEVMTransaction'
evmMessage:
description: If this is an EVM message, the message will be listed here.
allOf:
- $ref: '#/components/schemas/TransactionEVMMessage'
evmAccountDelegation:
description: If this is an EVM authorization, the authorization will be listed here.
allOf:
- $ref: '#/components/schemas/v2TransactionEVMAccountDelegation'
tronTransaction:
description: If this is a TVM transaction, the transaction will be listed here.
allOf:
- $ref: '#/components/schemas/v2TransactionTronTransaction'
btcTransaction:
description: 'For BTC transaction: Low level transaction details.'
allOf:
- $ref: '#/components/schemas/TransactionBTCTransaction'
btcPsbt:
description: 'For BTC PSBT: Details of the PSBT transaction.'
allOf:
- $ref: '#/components/schemas/v2TransactionBTCPSBT'
aptosTransaction:
description: 'For APTOS transaction: Low level transaction details.'
allOf:
- $ref: '#/components/schemas/TransactionAptosTransaction'
suiTransaction:
description: 'For SUI transaction: Low level transaction details.'
allOf:
- $ref: '#/components/schemas/TransactionSuiTransaction'
suiSignPersonalMessage:
description: Represents a Sui signPersonalMessage message.
allOf:
- $ref: '#/components/schemas/v2TransactionSuiSignPersonalMessage'
xrplTransaction:
description: 'For XRPL transaction: Low level transaction details.'
allOf:
- $ref: '#/components/schemas/TransactionXRPLTransaction'
substrateTransaction:
$ref: '#/components/schemas/TransactionSubstrateTransaction'
tonTransaction:
description: 'For TON transaction: Low level transaction details.'
allOf:
- $ref: '#/components/schemas/TransactionTonTransaction'
tonSignData:
description: Represents a TON SignData message.
allOf:
- $ref: '#/components/schemas/v2TransactionTonSignData'
tonProof:
description: Represents a TON Proof message.
allOf:
- $ref: '#/components/schemas/v2TransactionTonProof'
solanaSignMessage:
description: Represents a Solana signMessage message.
allOf:
- $ref: '#/components/schemas/v2TransactionSolanaSignMessage'
solanaTransaction:
description: 'For Solana transaction: Low level transaction details.'
allOf:
- $ref: '#/components/schemas/v2TransactionSolanaTransaction'
thetaTransaction:
description: 'For Theta transaction: Low level transaction details.'
allOf:
- $ref: '#/components/schemas/TransactionThetaTransaction'
stellarTransaction:
description: Represents a Stellar transaction.
readOnly: true
allOf:
- $ref: '#/components/schemas/v2TransactionStellarTransaction'
aleoTransaction:
description: Represents an Aleo transaction.
readOnly: true
allOf:
- $ref: '#/components/schemas/TransactionAleoTransaction'
createTime:
type: string
format: date-time
description: The time at which the transaction was created in the system.
readOnly: true
mineTime:
type: string
format: date-time
description: The time at which the transaction was mined.
readOnly: true
confirmTime:
type: string
format: date-time
description: The time at which the transaction was confirmed.
readOnly: true
expireTime:
type: string
format: date-time
description: The time at which the transaction was expired.
readOnly: true
spam:
type: boolean
replacementTransaction:
type: string
description: If the current transaction is dropped, the transaction that replaced it will be listed here.
readOnly: true
v2TransactionEVMTransactionAuthorization:
type: object
properties:
signer:
description: The signer address.
allOf:
- $ref: '#/components/schemas/apiv2Address'
contractAddress:
description: The address of the contract the account is delegating to.
allOf:
- $ref: '#/components/schemas/apiv2Address'
nonce:
type: string
format: int64
description: The nonce of the account for the delegation.
chainId:
type: string
description: The chain ID of the delegation.
signature:
type: string
format: byte
description: The signature of the delegation.
WalletCreateParams:
type: object
properties:
walletGroups:
type: array
example:
- vaults/1b25635a5b3f/walletGroups/95257c5a522f
items:
type: string
description: 'Wallet will be assigned to these wallet groups upon creation.
Each group must support assignment of empty wallets on creation in the dedicated group setting.
Format: `vaults/{vault_id}/walletGroups/{wallet_group_id}`.'
description: Parameters only used during wallet creation.
v2ConvertedValue:
type: object
properties:
amount:
type: string
description: The amount in USD.
readOnly: true
currencyCode:
type: string
description: The currency code of the amount. Always USD.
readOnly: true
description: A message representing a converted value.
StellarTransactionDecodedOperationBodySEP41Payment:
type: object
properties:
spenderAddress:
description: 'The address that authorized the transfer by consuming its allowance.
Only set when the underlying SEP41 function is `transfer_from`; unset
for a plain `transfer` (where the source address authorizes the
transfer itself).'
allOf:
- $ref: '#/components/schemas/apiv2Address'
sourceAddress:
title: 'The source of funds for the transfer. This address that authorized the
in case of a `transfer` call (i.e. the spender_address is empty)'
allOf:
- $ref: '#/components/schemas/apiv2Address'
destinationAddress:
description: The destination of funds for the transfer.
allOf:
- $ref: '#/components/schemas/apiv2Address'
contractAddress:
type: string
description: 'Example: `CB3WFHO46J3WGRAIARNT3XD4Z7NR5SZDNG3SVKN27GOTJAQGQFAH2KAJ`.'
title: The soroban contract address of the transferred token
assetRef:
type: string
description: 'A weak reference to the asset. The reference is not guaranteed to be valid.
Example: `assets/asset.stellar-mainnet.CB3WFHO46J3WGRAIARNT3XD4Z7NR5SZDNG3SVKN27GOTJAQGQFAH2KAJ`.'
rawAmount:
type: string
description: 'The raw amount (without decimals) of the payment.
Example: `10000000`.'
TransactionTransferPublicToPrivate:
type: object
properties:
sender:
$ref: '#/components/schemas/apiv2Address'
recipient:
$ref: '#/components/schemas/apiv2Address'
amount:
type: string
TransactionSubstrateTransaction:
type: object
properties:
fromAddress:
description: 'The source of the transfer. A `0x`-prefixed hex string address.
The extrinsic dispatcher''s address.'
allOf:
- $ref: '#/components/schemas/apiv2Address'
nonce:
type: string
format: int64
description: The nonce of the transaction.
encodedCall:
type: string
title: The hex encoded call
call:
title: The decoded representation of the call to be made
allOf:
- $ref: '#/components/schemas/SubstrateTransactionDecodedCall'
genesisHash:
type: string
title: The hex encoded genesis hash of the chain
TransactionEVMMessage:
type: object
properties:
type:
description: The type of the message.
allOf:
- $ref: '#/components/schemas/TransactionEVMMessageTypeEnum'
message:
type: string
description: The payload of the message as a plain UTF-8 string.
signature:
type: string
format: byte
description: ECDSA signature (65 bytes) of the message.
WalletconnectSessionPeer:
type: object
properties:
uri:
type: string
description: The URI of the peer.
name:
type: string
description: The name of the peer.
description:
type: string
description: The description of the peer.
icon:
type: string
description: The icon of the peer.
v2Balance:
type: object
properties:
asset:
type: string
example: assets/native.ethereum-mainnet
description: 'The resource name of the asset.
Format: `assets/{asset_id}`'
value:
type: string
example: '1.3'
description: The amount of the asset, in decimal form with precision included.
rawValue:
type: string
example: '13000000'
description: 'The raw amount of the asset that this balance contains.
Specified in the smallest unit of the Asset.'
frozenValue:
type: string
example: '0.3'
StellarTransactionStellarOperation:
type: object
properties:
sourceAccountAddress:
$ref: '#/components/schemas/apiv2Address'
rawBody:
type: string
format: byte
decodedBody:
$ref: '#/components/schemas/StellarTransactionDecodedOperationBody'
TransactionTonTransactionMessage:
type: object
properties:
address:
type: string
description: The destination of the call.
amount:
type: string
description: Native Nanoton amount to send.
payload:
type: string
title: 'The payload of the message.
If not provided - This means this message is a contract deployment or a native transfer'
stateInit:
type: string
description: The initial state of the message.
required:
- address
- amount
v2TransactionTonSignData:
type: object
properties:
schemaCrc:
type: string
format: int64
description: 'Indicates the layout of payload cell that in turn defines domain separation.
This is a descriptor of the content of the cell.'
cell:
type: string
description: The payload to sign.
publicKey:
type: string
description: The public key of the signer.
timestamp:
type: string
format: int64
description: The time at which the signature was created.
signature:
type: string
description: The signature of the typed data.
v2TransactionStellarTransactionMemo:
type: object
properties:
type:
description: The type of the memo.
allOf:
- $ref: '#/components/schemas/v2TransactionStellarTransactionMemoTypeEnum'
data:
type: string
description: The data of the memo.
required:
- type
- data
v2WalletEVMDetails:
type: object
properties:
address:
type: string
description: The address of the wallet.
readOnly: true
v2Wallet:
type: object
properties:
name:
type: string
example: vaults/1b25635a5b3f/wallets/95257c5a522f
description: 'The resource name of the wallet.
Format: `vaults/{vault_id}/wallets/{wallet_id}`'
readOnly: true
displayName:
type: string
example: DeFi wallet
description: 'A human-readable name.
Must match the regular expression `[a-zA-Z0-9\.,:\-''# _$]+$` and be shorter than 100 characters'
external:
type: boolean
description: 'Whether this wallet is external.
External wallets are wallets that are not managed by Utila.'
readOnly: true
archived:
type: boolean
description: Whether this wallet is archived.
readOnly: true
convertedValue:
description: 'The converted value of all assets in this Wallet.
Included only when `FULL` view is requested.
Note: this is an estimate, and may be out of date.'
readOnly: true
allOf:
- $ref: '#/components/schemas/v2ConvertedValue'
hasFrozenAssets:
type: boolean
example: true
description: 'Some of the assets in this wallet are frozen due to a AML policy.
Included only when `FULL` view is requested.'
readOnly: true
networks:
type: array
example:
- networks/ethereum-mainnet
items:
type: string
description: 'The resource names of the networks of the wallet. Can be set during creation and can
# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/utila/refs/heads/main/openapi/utila-balances-api-openapi.yml