Create Session

Open an authentication session

post

Registers a session for the caller's wallet using secp256k1 request signing.

Setup (all chains):

1. Generate a secp256k1 key pair on the client (32 random bytes → private key; derive compressed 33-byte public key).

2. Send clientPublicKey (compressed secp256k1, 33 bytes = 66 hex chars) in the request body.

3. Sign the raw request body with the secp256k1 private key (SHA-256 hash then compact ECDSA signature) — no route binding. This is the only route not bound to a "<METHOD> <routePath>" prefix, since no session exists yet to bind against.

4. Include x-hinkal-request-signature: <hex_compact_signature> in request headers.

5. Use the same key pair to authenticate all subsequent requests for this session — every other route binds the signature to its own route path (see AuthFields).

Session mode (useEIP712, default false):

• false = normal mode — secp256k1 request signature authenticates all requests including transactions. Session message includes the transaction consent line.

• true = EIP-712 mode — secp256k1 request signature for reads; per-transaction EIP-712/ed25519 signature for transaction endpoints. Session message omits the consent line.

Session message (the clientPublicKey line binds the secp256k1 key to the wallet signature):

• Normal mode: "Authorize Hinkal session\nSession ID: <sessionId>\nPublic Key: <clientPublicKey>\nThis signature can also be used to submit transactions."

• EIP-712 mode: "Authorize Hinkal session\nSession ID: <sessionId>\nPublic Key: <clientPublicKey>"

EVM: sign message with EIP-191 personal_sign. Tron: sign with tronWeb.trx.signMessageV2. Solana: sign UTF-8 message bytes with ed25519.

Header parameters

x-hinkal-request-signaturestringRequired

Hex-encoded compact secp256k1 signature over the raw request body: secp256k1_sign(SHA256(JSON.stringify(body))). This is the one route with no action binding — no session exists yet to bind against. Every other route binds the signature to its own "<METHOD> <routePath>"; see Authentication.

Body

signaturestringRequired

Chain-specific EIP-191 / ed25519 signature of the session message

addressstringRequired

Caller's wallet address (EVM/Tron hex address or Solana base58 public key)

sessionIdstring · uuidRequired

Session identifier — a UUID you generate, also embedded in the signed message. Used to look up this session in all subsequent requests.

noncestring · uuidRequired

Per-request UUID. Echoed back in the response body.

clientPublicKeystringRequired

Compressed secp256k1 public key (33 bytes, hex-encoded = 66 characters). The enclave stores this key and uses it to verify the x-hinkal-request-signature header on all subsequent requests for this session.

Example: 02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2

useEIP712booleanOptional

When false (default), opens a normal mode session — secp256k1 request signature authorizes all requests. When true, opens an EIP-712 mode session — each transaction requires a per-transaction typed-data signature.

Default: false

expiresAtstring · date-timeOptional

Optional ISO-8601 datetime at which the session should expire. Defaults to 24 hours from creation if omitted.

Example: 2025-01-01T12:00:00.000Z

Responses

200

Session created

application/json

400

Validation error

application/json

401

Invalid signature or reused nonce

application/json

409

Session ID already registered for a different owner.

application/json

500

Server error

application/json

post/create-session

POST /create-session HTTP/1.1
Host: api.hinkal.io
x-hinkal-request-signature: text
Content-Type: application/json
Accept: */*
Content-Length: 402

{
  "signature": "0x4a8f2b3c1d9e6f7a8b5c2d1e3f4a9b8c7d6e5f4a3b2c1d9e8f7a6b5c4d3e2f1a8b7c6d5e4f3a2b1c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8b1c",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "sessionId": "ffd74231-0672-48c7-bd82-9f72a803578b",
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "clientPublicKey": "02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "useEIP712": false
}

{
  "success": true,
  "expiresAt": "2025-06-17T12:00:00.000Z",
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}