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)

Field	Type	Required	Description
callback	string	✅	URL to be called after processing.
nonce	string	✅	Unique identifier for the request.

---

✅ Supported Actions

1. 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

Alias of request-accounts, returns the same result.

---

3. sign-message

Sign a message with the user's private key.

Fields in data

Field	Type	Required	Description
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 a PSBT (Partially Signed Bitcoin Transaction).

Fields in data

Field	Type	Required	Description
tx	string	✅	The base64 PSBT string to be signed.
options	object	❌	Optional signing options. Specs here

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

Code	Type	Description
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 and URL_SAFE flags.

• All JSON responses are encoded before returning.

---