Data Models

This document contains sanitized example data with dummy values

This page documents the data models and schemas used in the Universal Account API.

Authentication Models

JsonRPCRequestDto

Used for JSON-RPC requests to the bundler service.

{
  "jsonrpc": "2.0",
  "chainID": 1234,
  "apiKey": "1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
  "id": 0,
  "method": "eth_supportedEntryPoints",
  "params": []
}

Field	Type	Description	Required	Default
jsonrpc	string	The JSON-RPC version	Yes	"2.0"
chainID	number	The JSON-RPC chainID	Yes	1234
apiKey	string	Developer API key	Yes	-
id	any	Request identifier	No	0
method	string	Method to be invoked	Yes	-
params	array	Parameters for the method	No	[]

Web3SignDto

Used for Web3 wallet signature authentication.

{
  "signature": "0x1abc2def3456789abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345671c",
  "signer": "0x1234567890AbCdEf1234567890AbCdEf12345678"
}

Field	Type	Description	Required
signature	string	The signature of the user	Yes
signer	string	The un-capitalized address	Yes

LoginResponseDto

Response returned after successful authentication.

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshTokenExpire": 1710175253716,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "accessTokenExpire": 1710175253716,
  "userId": "0x1234567890abcdef1234567890abcdef12345678"
}

Field	Type	Description	Required
refreshToken	string	JWT refresh token	Yes
refreshTokenExpire	number	Refresh token expiration timestamp	Yes
accessToken	string	JWT access token	Yes
accessTokenExpire	number	Access token expiration timestamp	Yes
userId	string	The user's ID/address	Yes

RefreshTokenDto

Used to request a new access token.

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOnsidXNlcklkIjozLCJhcGlLZXkiOiJzeXMtZGV2LWFwaS1rZXkifSwiaWF0IjoxNzM4NzQ0NjkxLCJleHAiOjE3MzkzNDk0OTF9.EXAMPLE_SIGNATURE"
}

Field	Type	Description	Required
refreshToken	string	The refresh token of the user	Yes

Telegram Authentication Models

TelegramRequestOTPDTO

Used to request an OTP for Telegram authentication.

{
  "telegramId": "123456789"
}

Field	Type	Description	Required
telegramId	string	Unique Telegram ID of the user	Yes

TelegramLoginDTO

Used for Telegram login with OTP.

{
  "telegramId": "123456789",
  "username": "username123",
  "firstname": "FIRST",
  "lastname": "LAST",
  "avatarUrl": "https://example.com/avatar.jpg",
  "otp": "123456"
}

Field	Type	Description	Required
telegramId	string	Unique Telegram ID of the user	Yes
username	string	Telegram username	No
firstname	string	First name of the Telegram user	No
lastname	string	Last name of the Telegram user	No
avatarUrl	string	Avatar URL of the Telegram user	No
otp	string	OTP code for authentication	Yes

TelegramBotLoginDTO

Used to create a new user from Telegram bot login.

{
  "telegramId": "123456789",
  "username": "username123",
  "firstname": "FIRST",
  "lastname": "LAST",
  "domainId": 1,
  "sig": "0x1abc2def3456789abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345671b",
  "timestamp": 1741084672,
  "apiKey": "1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p"
}

Field	Type	Description	Required
telegramId	string	Unique Telegram ID of the user	Yes
username	string	Telegram username	No
firstname	string	First name of the Telegram user	No
lastname	string	Last name of the Telegram user	No
domainId	number	Domain ID that user is trying to log in	No
sig	string	Signature to verify the data from the login bot	Yes
timestamp	number	Timestamp when the bot signed the data	Yes
apiKey	string	API Key from the app for login	Yes

TelegramBotLoginGetSessionDTO

Used for getting a login session from Telegram bot.

{
  "state": "123456789",
  "code": "ABC123DEF456GHI"
}

Field	Type	Description	Required
state	string	State of login action	Yes
code	string	Session code to authorize the request	Yes

Email Authentication Models

EmailRequestOTPDTO

Used to request an OTP via email.

{
  "email": "[email protected]"
}

Field	Type	Description	Required
email	string	Unique email of the user	Yes

EmailOTPVerifyDTO

Used to verify an email OTP for login.

{
  "email": "[email protected]",
  "otp": "123456"
}

Field	Type	Description	Required
email	string	Email address of the user	Yes
otp	string	OTP code for authentication	Yes

OAuth Models

OauthCallbackDto

Used for OAuth provider callbacks.

{
  "code": "ABCD1234efgh5678IJKL9012mnop",
  "error": "mismatch_redirect_uri",
  "state": "eyJrZXkiOiIxYTJiM2M0ZDVlNmY3ZzhoOWkwajFrMmwzbTRuNW82cCIsIngtc2lnbmF0dXJlIjoiMHgxYWJjMmRlZjM0NTY3ODlhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxYyIsIngtdGltZXN0YW1wIjoiMTc0MDU1ODExMDEzMyIsIngtYXBpLWtleSI6IjFhMmIzYzRkNWU2ZjdnOGg5aTBqMWsybDNtNG41bzZwIiwib3JpZ2luIjoiaHR0cDovL2xvY2FsaG9zdDozMDAwIn0"
}

Field	Type	Description	Required
code	string	The code from the social provider	Yes
error	string	Error from the social provider	Yes
state	string	State from the social provider	Yes

User Profile Models

UpdateProfileDto

Used to update a user's profile information.

{
  "username": "john_doe",
  "firstname": "John",
  "lastname": "Doe",
  "avatar": "https://example.com/avatar.jpg",
  "signature": "Crypto enthusiast"
}

Field	Type	Description	Required	Max Length
username	string	Username for the user	No	50
firstname	string	User's first name	No	50
lastname	string	User's last name	No	50
avatar	string	URL to user's avatar image	No	-
signature	string	User signature or bio	No	200

UpdateTelegramDto

Used to update a user's Telegram information.

{
  "telegramId": "123456789",
  "telegramUsername": "@username123",
  "telegramFirstName": "First",
  "telegramLastName": "Last",
  "telegramAvatarUrl": "https://t.me/i/userpic/123.jpg",
  "telegramAuthDate": "2024-01-25T12:00:00Z",
  "telegramVerified": true
}

Field	Type	Description	Required	Max Length
telegramId	string	Telegram user ID	Yes	-
telegramUsername	string	Telegram username	No	50
telegramFirstName	string	First name from Telegram profile	No	50
telegramLastName	string	Last name from Telegram profile	No	50
telegramAvatarUrl	string	URL to Telegram profile picture	No	-
telegramAuthDate	date-time	Date when Telegram auth occurred	No	-
telegramVerified	boolean	Whether Telegram account is verified	No	-

Blockchain Models

SendTransactionDTO

Used to send blockchain transactions.

{
  "chainId": 1234,
  "sponsor": true,
  "transactionReq": {
    "to": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "value": "1000000000000000",
    "data": "0x",
    "maxPriorityFeePerGas": "1800000000"
  },
  "appApiKey": "1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p"
}

Field	Type	Description	Required
chainId	number	The blockchain chain ID	Yes
sponsor	boolean	Whether to use gas sponsorship	Yes
transactionReq	object	Transaction details object	Yes
appApiKey	string	API key for the app to send transaction to	No

Transaction Request Object

Field	Type	Description
to	string	Recipient address
value	string	Amount to send (in wei)
data	string	Transaction data (for contract interactions)
maxPriorityFeePerGas	string	Maximum priority fee per gas