Wallet

General Information

• All endpoints return data in JSON format
• All timestamps are in milliseconds (Unix epoch time) except where noted
• Session wallet timestamps (expiry, createdAt) are in seconds
• Wallet endpoints use address-based authentication (no JWT required)
• Transfer operations require signed transactions

Query Account Balance

GET /api/v1/wallet/balance

Get token balances for a wallet address.

Parameters:

Name	Type	Mandatory	Description
address	STRING	YES	Wallet address (0x...)

Response:

{
    "code": 200,
    "errMsg": "OK",
    "result": {
        "balances": [
            {
                "tokenId": "1",
                "locked": "0",
                "unlocked": "1.039709"
            },
            {
                "tokenId": "2",
                "locked": "100.5",
                "unlocked": "500.25"
            }
        ],
        "blockNumber": 12345678
    }
}

Response Fields:

Field	Type	Description
balances	ARRAY	Array of token balance objects
blockNumber	LONG	L2 block number at which the balances were queried
tokenId	STRING	Unique identifier for the token
locked	STRING	Amount locked in open orders (cannot be withdrawn)
unlocked	STRING	Available balance for trading or withdrawal (see Bridge for deposit/withdrawal details)

Withdraw Assets

POST /api/v1/wallet/withdraw

Submit a signed withdrawal transaction to move assets from L2 to Kaia L1.

Request Body:

{
    "tx": "0x02f8730183...{complete signed transaction hex}"
}

Request Fields:

Field	Type	Required	Description
tx	STRING	YES	Complete signed withdrawal transaction in hex format

Response:

{
    "code": 200,
    "errMsg": "OK",
    "result": "0x4c9980c4fd003e9aae2e7a8a87812382c84a695614225e423aaf1676089dbbfe"
}

Response Fields:

Field	Type	Description
result	STRING	Transaction hash for the withdrawal operation

Notes:

• For detailed withdrawal transaction creation and examples, see Bridge Documentation
• Withdrawals are processed automatically after submission
• Both KAIA and ERC20 token withdrawals are supported

Retry Failed Withdrawal

POST /api/v1/wallet/withdraw/retry

Retry a failed L2→L1 withdrawal using the latest confirmed Merkle root.

Request Body:

{
    "txHash": "0x123abc...def"
}

Request Fields:

Field	Type	Required	Description
txHash	STRING	YES	L2 withdrawal transaction hash to retry

Response:

{
    "code": 200,
    "errMsg": "OK",
    "result": "0x456def...789"
}

Response Fields:

Field	Type	Description
result	STRING	L1 execution transaction hash. Returns "0x0" if the withdrawal was already executed on L1 by an external transaction

Notes:

• This endpoint retries withdrawals that failed during the L1 execution phase
• A result of "0x0" indicates the withdrawal was already successfully completed on L1 (not by this request)

Get Session Wallets

GET /api/v1/wallet/session

Get all session wallets associated with an owner address.

Parameters:

Name	Type	Mandatory	Description
address	STRING	YES	Owner wallet address (0x...)

Response:

{
    "code": 200,
    "errMsg": "OK",
    "result": [
        {
            "name": "Trading Session 1",
            "expiry": 1758105316,
            "createdAt": 1757932516,
            "ownerAddress": "0x1234567890123456789012345678901234567890",
            "sessionAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "applied": true
        },
        {
            "name": "Trading Session 2",
            "expiry": 1758191716,
            "createdAt": 1758018916,
            "ownerAddress": "0x1234567890123456789012345678901234567890",
            "sessionAddress": "0xd02aaa39b223fe8d0a0e5c4f27ead9083c756cc3",
            "applied": false
        }
    ]
}

Response Fields:

Field	Type	Description
name	STRING	User-friendly name for the session wallet
expiry	LONG	Session expiry timestamp in seconds (Unix epoch)
createdAt	LONG	Session creation timestamp in seconds (Unix epoch)
ownerAddress	STRING	Main wallet address that owns this session wallet
sessionAddress	STRING	Temporary session wallet address for trading
applied	BOOLEAN	Whether the session wallet is currently active on-chain

Create Session Wallet

POST /api/v1/wallet/session

Create a new session wallet for delegated trading.

Request Body:

{
    "tx": "0x02f8730183...{complete signed transaction hex}",
    "name": "Trading Session 1"
}

Request Fields:

Field	Type	Mandatory	Description
tx	STRING	YES	Complete signed session wallet creation transaction in hex format
name	STRING	NO	Optional name for the session wallet

Response:

{
    "code": 200,
    "errMsg": "OK"
}

Notes:

• The transaction must be a valid session wallet creation transaction (see Transaction Structure)
• Owner address, session address, and expiry are extracted from the signed transaction
• The name field is optional and stored for display purposes only

Update Session Wallet

POST /api/v1/wallet/session/update

Update an existing session wallet's expiry time.

Request Body:

{
    "tx": "0x02f8730183...{complete signed transaction hex}"
}

Request Fields:

Field	Type	Mandatory	Description
tx	STRING	YES	Complete signed session wallet update transaction in hex format

Response:

{
    "code": 200,
    "errMsg": "OK"
}

Notes:

• The transaction must be a valid session wallet update transaction (see Transaction Structure)
• This endpoint only updates the expiry time; the name cannot be changed
• Owner address, session address, and new expiry are extracted from the signed transaction

Delete Session Wallet

POST /api/v1/wallet/session/delete

Delete a session wallet.

Request Body:

{
    "tx": "0x02f8730183...{complete signed transaction hex}"
}

Request Fields:

Field	Type	Mandatory	Description
tx	STRING	YES	Complete signed session wallet deletion transaction in hex format

Response:

{
    "code": 200,
    "errMsg": "OK"
}

Notes:

• The transaction must be a valid session wallet deletion transaction (see Transaction Structure)
• Owner address and session address are extracted from the signed transaction

Transfer Assets

POST /api/v1/wallet/transfer

Submit a signed transfer transaction to move assets between L2 addresses.

Request Body:

{
    "tx": "0x02f8730183...{complete signed transaction hex}"
}

Request Fields:

Field	Type	Required	Description
tx	STRING	YES	Complete signed transfer transaction in hex format

Response:

{
    "code": 200,
    "errMsg": "OK",
    "result": "0x4c9980c4fd003e9aae2e7a8a87812382c84a695614225e423aaf1676089dbbfe"
}

Response Fields:

Field	Type	Description
result	STRING	Transaction hash for the transfer operation

Notes:

• For detailed transfer transaction creation and examples, see Transaction Structure
• Both KAIA and ERC20 token transfers are supported
• The transaction is processed immediately by the sequencer

GET /api/v1/wallet/transfer

Query transfer history for a specific address.

Query Parameters:

Parameter	Type	Required	Description
address	STRING	YES	Wallet address to query transfer history for
token_id	INT64	NO	Filter by specific token ID
from	INT64	NO	Start timestamp in milliseconds (default: 0)
to	INT64	NO	End timestamp in milliseconds (default: current time)
limit	INT	NO	Number of records to return (default: 100, max: 500)

Response:

{
    "code": 200,
    "errMsg": "OK",
    "result": [
        {
            "id": 12345,
            "fromAddress": "0x1234567890123456789012345678901234567890",
            "toAddress": "0x0987654321098765432109876543210987654321",
            "txType": "Token Transfer",
            "tokenId": "1",
            "amount": "100.5",
            "status": "CONFIRMED",
            "timestamp": 1704067200000,
            "hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        }
    ]
}

Response Fields:

Field	Type	Description
id	INT64	Transfer record ID
fromAddress	STRING	Source address
toAddress	STRING	Destination address
txType	STRING	Transfer type (e.g., "Token Transfer")
tokenId	STRING	Token ID
amount	STRING	Transfer amount
status	STRING	Transfer status (e.g., "Success")
timestamp	INT64	Transfer timestamp in milliseconds
hash	STRING	Transaction hash

Notes:

• Results are returned in reverse chronological order (newest first)
• The from and to timestamps are in milliseconds (Unix epoch time)
• If token_id is not specified, transfers for all tokens are returned

POST Endpoints for Wallet Operations

All wallet POST operations (session wallet, transfers) require signed transactions sent to the fixed contract address.

For detailed transaction structure and examples, see Transaction Structure Documentation:

• Session Wallet Operations: Section 1
• Kaia Transfers: Section 7
• Token-specific Transfers: Command byte 0x11 (DexCommandTokenTransfer)

Notes

• All wallet addresses must be valid Ethereum addresses (0x...)
• All numeric values (amounts, balances) are returned as strings to preserve precision
• Most timestamps are in milliseconds (Unix epoch time); session wallet timestamps are in seconds
• Session wallets provide delegated trading capabilities with configurable expiry times
• Session wallet operations (create, update, delete) require signed transactions
• The locked balance represents funds tied up in open orders and cannot be withdrawn
• The unlocked balance is available for trading and withdrawal
• Transfer operations require properly signed transactions following the L2 transaction format
• For deposit and withdrawal operations between L1 and L2, see Bridge Documentation