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.


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.


Last updated