Blockchain API
Identity ENS lookups
ENS Name lookup
Used to lookup ENS name and avatar for the Ethereum address.
GET /v1/identity/{address}?projectId={projectId}
address
- (Optional) Ethereum address to lookup for the ENS name and avatar.projectId
- The project identifier.
Success response body:
{
"name": string,
"avatar": string
}
name
- Registered address ENS name.avatar
- URI of the avatar of presented.
Response error codes:
400 Bad request
- Wrong requested address format.
Hexless account profiles API
Email wallet users can register a profile name e.g. coolname.connect.id
and use it instead of the 0x
address.
Server API exposes forward lookup for the name.connect.id
-> 0x
address with chain IDs and reverse lookup for the 0x
-> name.connect.id
.
Users can also update the name data including avatar, bio and bind addresses.
Name lookup
Used to lookup address for the name.
GET /v1/profile/account/{name}
name
- The registered name. eg.coolname.connect.id
- Case insensitive alphabetic characters (a-z), numeric characters (0-9), the minus sign (-) and the period (.).
- Max 255 characters length.
Query parameters:
apiVersion
- (Optional) API version specification.1
by default. Can be2
to force using the updated API response.
Success response body:
{
"name": string,
"registered": number,
"updated": number,
"addresses": object[],
"attributes": object[],
}
name
- Registered account name.registered
- Unix time stamp of the name registration.updated
- Unix time stamp of the last name data update.addresses
- Registered addresses for the name:coin type
- Map where the key is the ENSIP-11 coin type:address
- Address according to the blockchain format.created
- Unix time stamp when the address was added.
attributes
- Key value object of the name attributes:avatar
- (Optional) avatar url.bio
- (Optional) account profile self description.
Name was not found response:
By default, or using apiVersion=1
query parameter the response will be HTTP 404
.
When using apiVersion=2
query parameter the response will be an empty array []
.
Response error codes:
400 Bad request
- Wrong requested name format.404 Not Found
- Default or when usingapiVersion=1
query parameter: the requested name is not registered.
Reverse name lookup
Lookup registered account name for the address in all chains:
GET /v1/profile/reverse/{address}
address
- The address for lookup in all chains. eg.0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb
Or the lookup for account name by the address in a specified chain:
GET /v1/profile/reverse/{coin_type}/{address}
coin_type
- ENSIP-11 coin type for the registered address and name.address
- Ihe address for lookup. eg.0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb
Query parameters:
apiVersion
- (Optional) API version specification.1
by default. Can be2
to force using the updated API response.
Success response body:
{
"name": string,
"registered": number,
"updated": number,
"addresses": object[],
"attributes": object[],
}
name
- Registered account name.registered
- Unix time stamp of the name registration.updated
- Unix time stamp of the last name data update.addresses
- Registered addresses for the name:coin_type
- Map where the key is the ENSIP-11 coin type:address
- Address according to the blockchain format.created
- Unix time stamp when the address was added.
attributes
- Key value object of the name attributes:avatar
- (Optional) avatar url.bio
- (Optional) account profile self description.
Name was not found response:
By default, or using apiVersion=1
query parameter the response will be HTTP 404
.
When using apiVersion=2
query parameter the response will be an empty array []
.
Response error codes:
400 Bad Request
- Wrong requested address format.404 Not Found
- Default or when usingapiVersion=1
query parameter: the requested address is not registered for any name or for the specified chain.
Name suggestion
Used to lookup for suggestions for the new name by returning 3 unique usernames.
GET /v1/profile/suggestions/:name
Path parameters
name
- The preffered name. Minimum 3 characters length.
Query parameters:
zone
- (Optional) Name zone for suggestions.
Success response body:
{
"suggestions": object[],
}
suggestions
- List of suggestions object. The default number of suggestions is up to 5:name
- Suggested name.registered
- Boolean parameter that reflects is the name is already registered. By default only not registered names are returned, but this is usefull for the exact name match that is also included in the response list.
Register the name
Used to register account name.
POST /v1/profile/account
Request body:
The POST request body should be in JSON format with the following structure:
{
"message": string,
"coin_type": string,
"signature": string,
"address":string,
}
message
- JSON serialized string that should contain the following fields:name
- The name to register e.g.coolname.connect.id
.- Alphabetic characters (A-Z a-z), numeric characters (0-9), the minus sign (-) and the period (.)
- 255 characters length limit.
attributes
- (Optional) key value object of the name attributes:avatar
- (Optional) avatar url.bio
- (Optional) account profile self description.
timestamp
- Current unixtime timestamp. The signature is valid for 10 seconds.
coin_type
- Coin type according to ENSIP-11 format. If not mainnet cointype60
is provided two address records will be added: for the provided cointype and for the mainnet.signature
- Ethereum signature for the signedmessage
to check the address ownership.address
- Address that bind to the account name.- 100 characters length limit.
Success response codes:
200 Ok
- Account name is successfully registered.
Response error codes:
400 Bad Request
- Some parameters in request body were missed or wrong.401 Unauthorized
- Signature verifying error.
Updating name attributes
Used to update name attributes.
POST /v1/profile/account/{name}/attributes
name
- The registered name. eg.coolname.wc.ink
Request body:
The POST request body should be in JSON format with the following structure:
{
"message": string,
"coin_type": string,
"signature": string,
"address":string,
}
message
- JSON serialized string that should contain the following fields:attributes
- Key value object of the name attributes:avatar
- (Optional) avatar url.bio
- (Optional) account profile self description.
timestamp
- Current unixtime timestamp. The signature is valid for 10 seconds.
coin_type
- Coin type according to ENSIP-11 format.signature
- Ethereum signature for the signedmessage
to check the address ownership.address
- Ownership address of the name.
Success response codes:
200 Ok
- Name attributes are successfully updated.
Response error codes:
400 Bad Request
- Some parameters in request body were missed or wrong.401 Unauthorized
- Signature verification or name address ownership error.
Updating name addresses
Used to update or add name addresses.
POST /v1/profile/account/{name}/address
name
- The registered name. eg.coolname.wc.ink
Request body:
The POST request body should be in JSON format with the following structure:
{
"message": string,
"coin_type": string,
"signature": string,
"address":string,
}
message
- JSON serialized string that should contain the following fields:coin_type
- Coin type of the new address according to ENSIP-11 format.address
- New address to bind to the account name for thecoin_type
.timestamp
- Current unixtime timestamp. The signature is valid for 10 seconds.
coin_type
- Coin type according to ENSIP-11 format.signature
- Ethereum signature for the signedmessage
to check the address ownership.address
- Ownership address of the name.
According to the ENSIP-11
only one address per coin_type
is supported. If an address is already assigned for the coin_type
that address will be updated.
Success response codes:
200 Ok
- Name addresses are successfully updated.
Response error codes:
400 Bad Request
- Some parameters in request body were missed or wrong.401 Unauthorized
- Signature verification or name address ownership error.
Generators
Pay SDK URL
This endpoint is used to generate the On Ramp Pay SDK URL.
POST /v1/generators/onrampurl?projectID={projectID}
projectId
- The project identifier
Request body:
The POST request body should be in JSON format with the following structure:
{
"destinationWallets": object[],
"partnerUserId": string,
"defaultNetwork": (optional) string,
"presetCryptoAmount": (optional) number,
"presetFiatAmount": (optional) number,
"defaultExperience": (optional) "send" | "buy",
"handlingRequestedUrls": (optional) bool
}
destinationWallets
- Array of objects which define blockchain types (blockchains) and destination addresses (address):address
- Destination address where the purchased tokens will be sent.blockchains
- (Optional) list of string blockchains enabled for the associated address.assets
- (Optional) list of string assets enabled for the associated address.supportedNetworks
- (Optional) list of strings with restricted networks available for the associated assets.
partnerUserId
- Unique ID representing the client app user. Must be less than 50 chars.defaultNetwork
- (Optional) default network as CAIP-2 that should be selected when multiple networks are present e.g.EIP155:1
for Ethereum.presetCryptoAmount
- (Optional) preset crypto amount value.presetFiatAmount
- (Optional) preset fiat amount value (for USD, CAD, GBP, EUR only). Ignored ifpresetCryptoAmount
is set.defaultExperience
- (Optional) default visual experience: either transfer funds from Coinbasesend
or buy assetsbuy
.handlingRequestedUrls
- (Optional) prevents the widget from opening URLs directly.
Success response body:
url
- Generated URL for the On Ramp Pay SDK.
Response error codes:
400 Bad Request
- Some parameters in request body were missed or wrong.401 Unauthorized
- ProjectID verification error.
Account
Balance
Used to lookup fungible assets balances
GET /v1/account/{address}/balance
Headers
x-sdk-version
- The AppKit release version must be provided in a request headers. Otherwise the response will be an empty array.
Path parameters
address
- The address for lookup. eg.0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb
Request arguments:
{
"projectId": string,
"currency": string,
"chain"?: string,
"forceUpdate"?: string
}
projectId
- The project identifier.currency
- Currency to calculate the assets value. e.g.usd
.- Supported currencies:
btc
,eth
,usd
,eur
,gbp
,aud
,cad
,inr
,jpy
.
- Supported currencies:
chain
- (Optional) Filter assets by CAIP-2 chain id. Supported chain IDs:eip155:1
- Ethereumeip155:5
- Goerlieip155:56
- BinanceSmartChaineip155:100
- GnosisChaineip155:250
- Fantomeip155:328
- ZkSyncEraeip155:137
- Polygoneip155:10
- Optimismeip155:8453
- Baseeip155:42220
- Celoeip155:42161
- Arbitrumeip155:43114
- Avalancheeip155:59160
- Lineaeip155:81032
- Blasteip155:8508132
- Scrolleip155:7854577
- Zoraeip155:1313161554
- Aurora
forceUpdate
- (Optional) List of comma separated token contract addresses (CAIP-10 format) to force the latest balance update on.chain
must be also provided for this type of call.
Success response body:
balances
- List of address balances with the following attributes:name
- Asset name. e.g.Ethereum
symbol
- Native asset or ERC-20 symbol. e.g.ETH
chainId
- CAIP-2 chain id. e.g.eip155:1
address
- (Optional) token contract address. The address is null for the native token.value
- (Optional) asset value in currency calculated from the request argument.price
- Price of a single unit of the asset in currency calculated from the request argument.quantity
- Asset quantity object:decimals
- Decimal number precision of the quantity.numeric
- Numeric representation of the asset quantity.
iconUrl
- URL of the asset icon.
Response error codes:
202 Accepted
- The data for the address is not fulfilled yet, re-trying is needed in up to 180 seconds.400 Bad request
- Wrong requested arguments format.
Transactions history
Used to lookup transactions list for an address.
GET /v1/account/{address}/history
Path parameters
address
- The address for lookup. eg.0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb
Query parameters:
{
projectId: string,
currency?: string,
cursor?: string,
onramp?: string
}
projectId
- Unique project ID.currency
- (Optional) Currency applied to prices. List of available currencies:BTC, ETH, USD, EUR, GBP, AUD, CAD, INR,JPY
.cursor
- (Optional) Cursor for the next page of (100) results from thenext
response field.onramp
- (Optional) Onramp history from the onramp provider. List of available providers:coinbase
.
Success response body object:
data
- List of transactions with the following attributes:id
- Unique transaction identifier.metadata
- Transaction metadata.operationType
- Operation type.hash
- Trnsaction hash.minedAt
- Unixtime of when the transaction was minted.sentFrom
- Sender address.sentTo
- Receiver address.status
- Status of the transaction.nonce
- Transaction nonce.application
- Application object:name
- Name of the item.iconUrl
- Icon representation of the item.
chain
- Chain ID.
transfers
- List of transfers inside of the transaction.fungible_info
- Transaction fungible info onject.nft_info
- Object of the NFT item if present.direction
- The direction of the transaction.quantity
- Quantity if the item was sent.value
- Value of the item in requestedcurrency
.price
- Price of the item in requestedcurrency
.
next
- Cursor for the next page of (100) results.
Response error codes:
400 Bad request
- Wrong requested arguments format.
Fungibles
Price
Lookup for the current price of the fungible assset item:
POST /v1/fungible/price
Request body:
The POST request body should be in JSON format with the folowing structure:
projectId
- The project identifier.currency
- Currency for the price calculation e.g.usd
.- Supported currencies:
usd
,eur
,gbp
,aud
,cad
,inr
,jpy
,btc
,eth
.
- Supported currencies:
addresses
- Asset's contract addresses array of strings in CAIP-10 format.
Success response body:
{
"fungibles": object[],
}
fungibles
- List of objects with fungibles on the requested address:address
- Asset implementation address.name
- Asset name. e.g.Ethereum
.symbol
- Native asset or ERC-20 symbol. e.g.ETH
.iconUrl
- URL of the asset icon.price
- Price of a single unit of the asset in currency calculated from the request argument.
Response error codes:
400 Bad Request
- Required argument is missed in the request.422 Unprocessable Entity
- Wrong argument(s) format was passed to the request.
Conversion
Endpoints to convert tokens.
List of tokens available for conversion
GET /v1/convert/tokens
Path parameters
projectId
- The project identifierchainId
- Filter by chain. CAIP-2 format. e.g.eip155:1
Success response body:
tokens
- List of objects which define available tokens:name
- Token name.symbol
- Token symbol.address
- Contract address of the token in CAIP-10 format.decimals
- Number of decimals for amount supported by a given token.logoUri
- URL of the token icon.eip2612
- (Optional for ERC-20 tokens) value istrue
if the token supports eip-2612
Response error codes:
400 Bad Request
- Some parameters in request body were missed or wrong.401 Unauthorized
- Project ID verification error.
Requesting conversion quotes
GET /v1/convert/quotes
Path parameters
projectId
- The project identifier.amount
- Amount of tokens to be converted related to the decimals of the token. Numeric value up to 18 decimals.userAddress
- Caller address.from
- Source CAIP-10 asset address.to
- Destination CAIP-10 asset address.gasPrice
- (Optional) Network price per gas in wei. By default fast network gas price.
Success response body:
quotes
- List of objects which define available conversion quotes:id
- (Optional for cross chain swaps) quote ID to be used for convert request.fromAmount
- Amount of token being sent on sending chain.fromAccount
- Source CAIP-10 account ID.toAmount
- Amount of token to be received on the destination chain.toAccount
- Destination CAIP-10 account ID.
Response error codes:
400 Bad Request
- Some parameters in request body were missed or wrong.401 Unauthorized
- Project ID verification error.
Requesting approve calldata
Generate approve calldata to allow a transaction to perform a conversion.
This step should be skipped if the token supports eip-2612.
In this case, the permit
parameter in Requesting calldata to convert
should be used to provide the approval signature.
GET /v1/convert/build-approve
Path parameters
projectId
- The project identifier.userAddress
- Caller address.from
- Source CAIP-10 asset address.to
- Destination CAIP-10 asset address.amount
- (Optional) Amount of tokens to be converted related to the decimals of the token. If not specified an infinite amount of tokens will be allowed to spend.
Success response body:
tx
- Transaction objectfrom
- (Optional) Source.to
- Destination.data
- Transaction data.value
- Amount of tokens to be converted, denominated in the decimal precision of the token.eip155
- (Optional) For EVM conversions only.gasPrice
- Current gas price.
Response error codes:
400 Bad Request
- Some parameters in request body were missing or wrong.401 Unauthorized
- Project ID verification error.
Requesting calldata to convert
Generate calldata for convert transaction.
POST /v1/convert/build-transaction
Request body
The POST
request body should be in JSON format with the following structure:
projectId
- The project identifier.userAddress
- Caller address.from
- Asset source CAIP-10 address.to
- Asset destination CAIP-10 address.amount
- Amount of tokens to be converted denominated in the decimal precision of the token.eip155
- (Optional) For EVM converts onlyslippage
- Slippage integer value. Max. 50permit
- (Optional) EIP-2612 gasless approvals.
Success response body:
tx
- Transaction objectfrom
- Source address (Sender).to
- Destination address (Smart contract to swap).data
- Transaction data.amount
- Amount of tokens to be received denominated in the decimal precision of the token.eip155
- (Optional) For EVM converts onlygas
- Gas amount to be used.gasPrice
- Current gas price.
Response error codes:
400 Bad Request
- Some parameters in request body were missing or wrong.401 Unauthorized
- Project ID verification error.
Gas price
GET /v1/convert/gas-price
Path parameters
projectId
- The project identifierchainId
- Chain ID in CAIP-2 format. e.g.eip155:1
Success response body:
standard
- Standard gas price.fast
- Fast gas price.instant
- Instant gas price.
Conversion allowance
GET /v1/convert/allowance
Path parameters
projectId
- The project identifier.tokenAddress
- Token address in CAIP-10 format. e.g.eip155:1:0x...
.userAddress
- User wallet address in CAIP-10 format. e.g.eip155:1:0x...
.
Success response body:
allowance
- Conversion allowance amount.
Response error codes:
400 Bad Request
- Some parameters in request body were missed or wrong.401 Unauthorized
- Project ID verification error.