Signing & Endorsed Requests

Every action that changes wallet state in Dakota — sending funds, attaching a signer group, modifying a policy — requires an endorsed request: a cryptographically signed declaration of intent. This guide explains the signing model end-to-end, documents every intent type, and walks through the full signer group and policy lifecycles.

If you haven’t set up a wallet yet, start with Non-Custodial Wallets first, then return here for the complete signing reference.

The Endorsed Request Model

An endorsed request wraps two things:

An intent — a JSON object describing exactly what you want to do
One or more signatures — ECDSA P-256 signatures proving that authorized signers approved the intent

{
  "signatures": [
    "<base64-encoded ECDSA signature>"
  ],
  "intent": {
    "type": "attach_group_to_wallet",
    "wallet_id": "wal_...",
    "group_id": "grp_...",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Dakota’s policy engine re-canonicalizes the intent server-side, verifies each signature against the stored public keys, checks that the signer group’s approval threshold is met, and only then executes the action. This means:

You never send private keys — only signatures
The server cannot fabricate intents — every action has cryptographic proof of authorization
Multiple signers can co-approve — the signatures array accepts as many entries as your threshold requires

How Signing Works

Every signature follows the same three-step process, regardless of intent type.

Step 1: Build the Intent JSON

Create the intent object with the exact fields required for the operation. Field names are snake_case. Amounts are strings (e.g., "10.5", not 10.5). Omit any optional fields that don’t apply.

Step 2: Canonicalize with RFC 8785 (JCS)

RFC 8785 JSON Canonicalization Scheme produces a deterministic byte sequence from any JSON object by sorting keys alphabetically and removing insignificant whitespace. This ensures that your client and Dakota’s policy engine hash identical bytes, regardless of how your language orders JSON keys.

Step 3: Hash with SHA-256, Sign with ECDSA P-256

Hash the canonical bytes with SHA-256, then sign the hash using your ECDSA P-256 private key. The signature must be in ASN.1 DER encoding (not raw r || s), then base64-encoded.

Intent JSON → RFC 8785 canonicalize → SHA-256 hash → ECDSA P-256 sign (DER) → Base64 encode

Code Examples

import { createSign } from 'node:crypto';
import canonicalize from 'canonicalize'; // npm install canonicalize

function signIntent(intent, privateKey) {
  const canonical = canonicalize(intent);
  const signer = createSign('SHA256');
  signer.update(canonical);
  const signature = signer.sign({ key: privateKey, dsaEncoding: 'der' });
  return signature.toString('base64');
}

Browser only: crypto.subtle.sign with ECDSA returns an IEEE P1363 raw r || s encoding, not ASN.1 DER. You must convert it before submitting — the rawEcdsaSignatureToDer helper above does this. Submitting the raw form will fail signature verification.

Intent Types Reference

Every endorsed request carries one of nine intent types. The table below lists all of them with their discriminator value, endpoint, and required fields.

Intent	`type` value	Endpoint	Required Fields
Send Transaction	(none)	`POST /wallets/{wallet_id}/transactions`	`wallet_id`, `caip2`, `operation`, `idempotency_key`
Attach Signer Group	`attach_group_to_wallet`	`PUT /wallets/{wallet_id}/signer-groups/{group_id}`	`type`, `wallet_id`, `group_id`, `idempotency_key`
Detach Signer Group	`detach_group_from_wallet`	`DELETE /wallets/{wallet_id}/signer-groups/{group_id}`	`type`, `wallet_id`, `group_id`, `idempotency_key`
Attach Policy	`attach_policy_to_wallet`	`PUT /policies/{policy_id}/wallets/{wallet_id}`	`type`, `wallet_id`, `policy_id`, `idempotency_key`
Detach Policy	`detach_policy_from_wallet`	`DELETE /policies/{policy_id}/wallets/{wallet_id}`	`type`, `wallet_id`, `policy_id`, `idempotency_key`
Add Policy Rule	`add_policy_rule`	`POST /policies/{policy_id}/rules`	`type`, `policy_id`, `rule_type`, `action`, `definition`, `idempotency_key`
Remove Policy Rule	`remove_policy_rule`	`DELETE /policies/{policy_id}/rules/{rule_id}`	`type`, `policy_id`, `rule_id`, `idempotency_key`
Update Policy Rule	`update_policy_rule`	`PATCH /policies/{policy_id}/rules/{rule_id}`	`type`, `policy_id`, `rule_id`, `updated_definition`, `idempotency_key`
Delete Policy	`delete_policy`	`DELETE /policies/{policy_id}`	`type`, `policy_id`, `idempotency_key`

Send Transaction

Send crypto from a wallet. This is the only intent type without a type discriminator field.

{
  "wallet_id": "wal_2LfZm5KMnRvLFtRP7nJJug4zJEP",
  "caip2": "eip155:1",
  "operation": {
    "kind": "transfer",
    "from": "0xYourWalletAddress...",
    "to": "0xDestinationAddress...",
    "amount": "10.5",
    "asset_id": "USDC"
  },
  "idempotency_key": "a6f8c8c0-6f0a-4a24-a3a3-9e8a0cf2f7c0"
}

The operation.kind field determines which sub-fields are required:

Kind	Required Fields	Optional Fields
`transfer`	`from`, `to`, `amount`, `asset_id`	—
`contract_call`	`from`, `to`, `asset_id`	`method`, `args`, `data`

Amounts are strings ("10.5", not 10.5). The caip2 field uses CAIP-2 chain identifiers (e.g., eip155:1 for Ethereum mainnet, eip155:11155111 for Sepolia).

Attach Signer Group to Wallet

{
  "type": "attach_group_to_wallet",
  "wallet_id": "wal_2LfZm5KMnRvLFtRP7nJJug4zJEP",
  "group_id": "grp_2LfPqT9VmQzKDvQP9rGHth3yHCN",
  "idempotency_key": "b7e9d1a2-3c4f-5e6d-7a8b-9c0d1e2f3a4b"
}

Detach Signer Group from Wallet

{
  "type": "detach_group_from_wallet",
  "wallet_id": "wal_2LfZm5KMnRvLFtRP7nJJug4zJEP",
  "group_id": "grp_2LfPqT9VmQzKDvQP9rGHth3yHCN",
  "idempotency_key": "c8f0e2b3-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

Attach Policy to Wallet

{
  "type": "attach_policy_to_wallet",
  "wallet_id": "wal_2LfZm5KMnRvLFtRP7nJJug4zJEP",
  "policy_id": "pol_2LfQm5KMnRvLFtRP7nJJug4zJEP",
  "idempotency_key": "d9a1f3c4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

Detach Policy from Wallet

{
  "type": "detach_policy_from_wallet",
  "wallet_id": "wal_2LfZm5KMnRvLFtRP7nJJug4zJEP",
  "policy_id": "pol_2LfQm5KMnRvLFtRP7nJJug4zJEP",
  "idempotency_key": "e0b2a4d5-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
}

Add Policy Rule

{
  "type": "add_policy_rule",
  "policy_id": "pol_2LfQm5KMnRvLFtRP7nJJug4zJEP",
  "rule_type": "approval_threshold",
  "action": "allow",
  "definition": {
    "threshold": 2,
    "description": "Require 2 approvals"
  },
  "idempotency_key": "f1c3b5e6-7a8b-9c0d-1e2f-3a4b5c6d7e8f"
}

Available rule types:

`rule_type`	`action`	`definition` example
`approval_threshold`	`allow`	`{"threshold": 2, "description": "Require 2 approvals"}`
`amount_threshold`	`deny`	`{"amount": "10000", "currency": "USD"}`
`address_list`	`allow` or `deny`	Address allowlist/denylist configuration

Remove Policy Rule

{
  "type": "remove_policy_rule",
  "policy_id": "pol_2LfQm5KMnRvLFtRP7nJJug4zJEP",
  "rule_id": "rule_2N4YkKpKu7M3mKpGYmF8kcJ8oZT",
  "idempotency_key": "a2d4c6e7-8b9c-0d1e-2f3a-4b5c6d7e8f9a"
}

Update Policy Rule

{
  "type": "update_policy_rule",
  "policy_id": "pol_2LfQm5KMnRvLFtRP7nJJug4zJEP",
  "rule_id": "rule_2N4YkKpKu7M3mKpGYmF8kcJ8oZT",
  "updated_definition": "{\"amount\": \"15000\", \"currency\": \"USD\"}",
  "idempotency_key": "b3e5d7f8-9c0d-1e2f-3a4b-5c6d7e8f9a0b"
}

updated_definition is a JSON string, not a nested object. Serialize the definition object to a string before including it in the intent.

Delete Policy

{
  "type": "delete_policy",
  "policy_id": "pol_2LfQm5KMnRvLFtRP7nJJug4zJEP",
  "idempotency_key": "c4f6e8a9-0d1e-2f3a-4b5c-6d7e8f9a0b1c"
}

Deleting a policy is irreversible. Detach the policy from all wallets first — attempting to delete a policy that is still attached to a wallet will fail.

Signer Group Lifecycle

A signer group controls who can authorize wallet actions. Here is the complete lifecycle from creation through teardown.

Step-by-step

Step	Action	Endpoint	Endorsed?	Prerequisites
1	Register signers	`POST /signers`	No	Generate ES256 keypairs client-side
2	Create signer group	`POST /signer-groups`	No	At least one registered signer public key
3	Add more signers	`POST /signer-groups/{id}/signers`	No	Signer public key already registered
4	Attach group to wallet	`PUT /wallets/{id}/signer-groups/{group_id}`	Yes	Group exists, wallet exists
5	Send transactions	`POST /wallets/{id}/transactions`	Yes	Group attached, threshold met
6	Remove a signer	`DELETE /signer-groups/{id}/signers/{signer_id}`	No	Signer is a member of the group
7	Detach group from wallet	`DELETE /wallets/{id}/signer-groups/{group_id}`	Yes	Group is attached to wallet

Before detaching a signer group, ensure the wallet has at least one other signer group attached, or the wallet will become unusable — no one will be able to sign transactions for it.

Adding and removing signers (steps 3 and 6) do not require endorsed requests — they are standard API calls authenticated with your API key. Only wallet-level operations (attach, detach, transact) require cryptographic signatures.

Policy Lifecycle

Policies define automated governance rules for wallets — approval thresholds, amount limits, address allowlists, and more. Here is the complete lifecycle.

Step-by-step

Step	Action	Endpoint	Endorsed?	Prerequisites
1	Create policy	`POST /policies`	No	Signer group exists
2	Add rules	`POST /policies/{id}/rules`	Yes	Policy exists
3	Attach to wallet	`PUT /policies/{id}/wallets/{wallet_id}`	Yes	Policy has at least one rule
4	Update a rule	`PATCH /policies/{id}/rules/{rule_id}`	Yes	Rule exists on policy
5	Detach from wallet	`DELETE /policies/{id}/wallets/{wallet_id}`	Yes	Policy is attached to wallet
6	Remove rules	`DELETE /policies/{id}/rules/{rule_id}`	Yes	Rule exists, policy detached from wallets
7	Delete policy	`DELETE /policies/{id}`	Yes	Policy is detached from all wallets

Deletion order matters. You must detach a policy from all wallets before you can delete it. Attempting to delete an attached policy will return an error.

Troubleshooting

Signature Verification Failed

Symptom	Cause	Fix
`invalid_signature`	Signature is in IEEE P1363 format (`r \|\| s`) instead of ASN.1 DER	Use `dsaEncoding: 'der'` in Node.js, or convert with `rawEcdsaSignatureToDer` in browsers. See code examples.
`invalid_signature`	Canonicalization mismatch — client and server produced different bytes	Ensure you are using an RFC 8785 JCS library (`canonicalize` for JS, `jcs` for Python, `json-canonicalization` for Go). Standard `JSON.stringify` is not deterministic.
`invalid_signature`	Amount passed as number instead of string	Use `"10.5"` not `10.5`. Numbers and strings canonicalize differently.
`invalid_signature`	Extra or missing fields in the intent	The intent you sign must have exactly the fields the server expects. Omit optional fields you are not using — do not set them to `null`.

Threshold Not Met

Symptom	Cause	Fix
`threshold_not_met`	Fewer signatures than the policy’s approval threshold	If the policy requires 2-of-3, the `signatures` array must contain at least 2 valid signatures from distinct signers in the group.

Signer Not Authorized

Symptom	Cause	Fix
`signer_not_found`	The signing key is not a member of any signer group attached to the wallet	Verify the public key is registered as a signer, added to a signer group, and that group is attached to the wallet.
`signer_not_found`	Wrong private key used for signing	Ensure you are signing with the private key that corresponds to the public key registered with Dakota.

Key Format Errors

Symptom	Cause	Fix
`400` on `POST /signers`	Public key is not a valid P-256 SPKI	Export the public key as X.509 SubjectPublicKeyInfo in DER format, then base64-encode it. Keys on other curves (P-384, P-521, secp256k1) are rejected.
`400` on `POST /signers`	Key type mismatch	Ensure `key_type` is `"ES256"` for ECDSA P-256 keys or `"WEBAUTHN"` for WebAuthn keys.

Documentation

Authentication

SDKs & Libraries

Developers

Signing & Endorsed Requests

The Endorsed Request Model

How Signing Works

Step 1: Build the Intent JSON

Step 2: Canonicalize with RFC 8785 (JCS)

Step 3: Hash with SHA-256, Sign with ECDSA P-256

Code Examples

Intent Types Reference

Send Transaction

Attach Signer Group to Wallet

Detach Signer Group from Wallet

Attach Policy to Wallet

Detach Policy from Wallet

Add Policy Rule

Remove Policy Rule

Update Policy Rule

Delete Policy

Signer Group Lifecycle

Step-by-step

Policy Lifecycle

Step-by-step

Troubleshooting

Signature Verification Failed

Threshold Not Met

Signer Not Authorized

Key Format Errors

Documentation

Authentication

SDKs & Libraries

Developers

​The Endorsed Request Model

​How Signing Works

​Step 1: Build the Intent JSON

​Step 2: Canonicalize with RFC 8785 (JCS)

​Step 3: Hash with SHA-256, Sign with ECDSA P-256

​Code Examples

​Intent Types Reference

​Send Transaction

​Attach Signer Group to Wallet

​Detach Signer Group from Wallet

​Attach Policy to Wallet

​Detach Policy from Wallet

​Add Policy Rule

​Remove Policy Rule

​Update Policy Rule

​Delete Policy

​Signer Group Lifecycle

​Step-by-step

​Policy Lifecycle

​Step-by-step

​Troubleshooting

​Signature Verification Failed

​Threshold Not Met

​Signer Not Authorized

​Key Format Errors

The Endorsed Request Model

How Signing Works

Step 1: Build the Intent JSON

Step 2: Canonicalize with RFC 8785 (JCS)

Step 3: Hash with SHA-256, Sign with ECDSA P-256

Code Examples

Intent Types Reference

Send Transaction

Attach Signer Group to Wallet

Detach Signer Group from Wallet

Attach Policy to Wallet

Detach Policy from Wallet

Add Policy Rule

Remove Policy Rule

Update Policy Rule

Delete Policy

Signer Group Lifecycle

Step-by-step

Policy Lifecycle

Step-by-step

Troubleshooting

Signature Verification Failed

Threshold Not Met

Signer Not Authorized

Key Format Errors