Deep Link Specification
This document describes the deep link structure and response formats for the Tokeo mobile wallet. This includes supported operations, parameters, expected behavior, and error handling standards.
📥 Incoming Deep Links
Deep links follow the format:
tokeo://<action>?data=<base64-encoded-json>
The data
query parameter is a base64url-encoded JSON object. All requests must contain:
callback
: a URL that the wallet should call when responding.nonce
: a unique string that the DApp can use to correlate the response.
🔐 Common Parameters (in data
JSON)
data
JSON)callback
string
✅
URL to be called after processing.
nonce
string
✅
Unique identifier for the request.
✅ Supported Actions
1. request-accounts
request-accounts
Request the user's BTC address.
Example Request
tokeo://request-accounts?data=eyJjYWxsYmFjayI6Imh0dHBzOi8vZXhhbXBsZS5jb20vY2IiLCJub25jZSI6IjEyMzQ1NiJ9
Response
Success:
{
"accounts": [{
"address": "bc1pabc123...",
"type": "p2tr",
"network": "mainnet",
"publicKey": "abcdef1234567890..." // 64-character hex (x-only Taproot pubkey)
}]
}
Returned as:
https://example.com/cb?data=<base64-encoded-json>&nonce=123456
Error:
{
"type": "user_rejection",
"message": "User rejected account request",
"details": "User declined to connect wallet",
"code": 1001
}
Returned as:
https://example.com/cb?error=<base64-encoded-json>&nonce=123456
2. get-accounts
get-accounts
Alias of request-accounts
, returns the same result.
3. sign-message
sign-message
Sign a message with the user's private key.
Fields in data
msg
string
✅
The message to be signed.
curve
string
❌
One of ecdsa
(default) or secp256k1
Success Response
{
"signature": "..."
}
Error Example
{
"type": "signing_error",
"message": "Failed to sign message",
"details": "Message was empty",
"code": 1003
}
4. sign-psbt
sign-psbt
Sign a PSBT (Partially Signed Bitcoin Transaction).
Fields in data
tx
string
✅
The base64 PSBT string to be signed.
Success Response
{
"signature": "...signed psbt..."
}
Error Response
{
"type": "signing_error",
"message": "Failed to sign PSBT",
"details": "base64 parse failure",
"code": 1003
}
🔁 Response Format
All responses to a callback
URL include:
?data=<base64 encoded JSON>
for success?error=<base64 encoded JSON>
for errors&nonce=<original nonce>
is always appended
Example:
https://example.com/callback?data=...&nonce=12345
https://example.com/callback?error=...&nonce=12345
❗ Error Codes
1001
user_rejection
User manually declined a request.
1002
invalid_request
Malformed or missing input from DApp.
1003
signing_error
Failure during signing (exception, invalid input).
1006
internal_error
Unexpected app crash or internal issue.
🛠️ Notes
nonce
is not validated by the wallet, but must be returned for the DApp to match responses.callback
must be HTTPS.Base64 is URL-safe encoded with
NO_WRAP
andURL_SAFE
flags.All JSON responses are encoded before returning.
Last updated