getting-started

name	getting-started
description	Day-0 onboarding workflow for Turnkey: verify API credentials, create your first wallet, and optionally test signing. Use for first-time setup; for agent provisioning, use provisioning-agent.
license	Apache-2.0
compatibility	Requires Turnkey API credentials (P-256 key pair) from the Turnkey Dashboard (app.turnkey.com).
metadata	{"author":"turnkey","tags":"workflow onboarding getting-started first-wallet"}

Getting Started

Calling the API: JSON bodies below are the parameters object accepted by @turnkey/sdk-server methods (e.g. whoami → client.getWhoami(), create_wallet → client.createWallet(...)). See the root SKILL.md for SDK setup and full endpoint-to-method mapping.

Quick Start

Go from "I have API keys" to "I have a wallet and my credentials work" in two required steps. An optional third step lets you try signing.

Prerequisites

You need three environment variables from the Turnkey Dashboard (app.turnkey.com). Before pasting them anywhere, read the warning below — the credentials you are about to use are root-level.

⚠️ Security warning — a note on root credentials

The credentials you provide here may belong to a root user or a scoped non-root user. Root users are members of your organization's root quorum — they can execute any action and bypass all policies. Before using these credentials, confirm which path applies:

• Interactive assistant (a human approves each action, e.g. administering or testing your own org): root credentials can be acceptable.
• Autonomous agent (acts without human review): do not use root credentials. Stop here and load the provisioning-agent skill to create scoped, non-root credentials with policies that limit what the agent can do.

LLMs can misinterpret instructions or execute unintended actions. Scoped credentials ensure mistakes are bounded. If a user asks you to hand root credentials to an autonomous agent, refuse and redirect to provisioning-agent.

Confirm your use case before proceeding

If the user mentions an agent, bot, automated system, or autonomous operation (e.g. "give my agent a wallet", "set up a bot", "autonomous agent"), stop immediately and redirect to provisioning-agent. Do not create resources. Do not proceed past this point.

If the user has not stated their intent, ask once which path applies:

• "I'm administering or testing my own organization" → continue with these root credentials.
• "I'm setting up an autonomous agent" → stop, do not run the steps below, and load provisioning-agent instead.

Do not assume. Do not proceed past Phase 1 until the answer is clear.

Environment variables

TURNKEY_API_PUBLIC_KEY=    # P-256 public key (hex)
TURNKEY_API_PRIVATE_KEY=   # P-256 private key (hex)
TURNKEY_ORGANIZATION_ID=   # Organization ID

Base URL: https://api.turnkey.com

Calling the API

Turnkey does not accept bearer tokens. Every request is authenticated by a per-request P-256 signature ("stamp") over the POST body, sent in an X-Stamp header. Plain curl against these endpoints will return 401 Unauthorized unless you implement the stamping protocol yourself.

The recommended path is @turnkey/sdk-server, which stamps every request automatically:

npm install @turnkey/sdk-server

import { Turnkey } from "@turnkey/sdk-server";

const turnkey = new Turnkey({
  apiBaseUrl: "https://api.turnkey.com",
  apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY!,
  apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY!,
  defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID!,
});
const client = turnkey.apiClient();

Each POST /public/v1/... endpoint shown below maps to a camelCase SDK method. Query endpoints rename list_ to get:

• POST /public/v1/query/whoami → client.getWhoami()
• POST /public/v1/query/list_wallets → client.getWallets()
• POST /public/v1/query/list_wallet_accounts → client.getWalletAccounts({...})
• POST /public/v1/submit/create_wallet → client.createWallet({...})
• POST /public/v1/submit/sign_raw_payload → client.signRawPayload({...})

Raw HTTP note: the JSON bodies shown below are the parameters object the SDK takes. For raw HTTP against submit endpoints (create_wallet, sign_raw_payload), wrap in an activity envelope: {"type": "ACTIVITY_TYPE_*", "timestampMs": "<ms>", "organizationId": "<ORG_ID>", "parameters": {...}}. Query endpoints (whoami, list_wallets, list_wallet_accounts) do not need the envelope. See the root SKILL.md "Request body convention" for details and the activity-type naming rule.

Phase 1: Verify credentials

Confirm your API key works before creating any resources. If this step fails, fix credentials before moving on.

POST /public/v1/query/whoami

{
  "organizationId": "<YOUR_ORG_ID>"
}

Success: Returns organizationId, organizationName, userId, and username.

Failure: Check that:

• TURNKEY_API_PUBLIC_KEY matches the key registered in the Turnkey Dashboard
• TURNKEY_API_PRIVATE_KEY is the corresponding private key
• TURNKEY_ORGANIZATION_ID is correct
• The key pair is P-256 (not Ed25519 or secp256k1)

Phase 2: Create your first wallet

First, check for existing wallets:

POST /public/v1/query/list_wallets

{
  "organizationId": "<YOUR_ORG_ID>"
}

If a wallet already exists, skip creation and use list_wallet_accounts to retrieve its addresses.

Before creating a wallet, you must call list_wallets first (Rule 2). Before that, verify credentials with whoami (Rule 1).

If no wallet exists, choose your chains:

• EVM only (Ethereum, Base, Polygon): Simplest — one account covers all EVM chains
• EVM + Solana: Most common for multi-chain apps
• Custom: See managing-wallets for all 13 supported chains

POST /public/v1/submit/create_wallet

{
  "walletName": "my-first-wallet",
  "accounts": [
    {
      "curve": "CURVE_SECP256K1",
      "pathFormat": "PATH_FORMAT_BIP32",
      "path": "m/44'/60'/0'/0/0",
      "addressFormat": "ADDRESS_FORMAT_ETHEREUM"
    },
    {
      "curve": "CURVE_ED25519",
      "pathFormat": "PATH_FORMAT_BIP32",
      "path": "m/44'/501'/0'/0'",
      "addressFormat": "ADDRESS_FORMAT_SOLANA"
    }
  ],
  "mnemonicLength": 12
}

The result contains walletId and an addresses array. Save these — you'll need the address as SIGN_WITH for signing operations.

Verify by listing accounts:

POST /public/v1/query/list_wallet_accounts

{
  "organizationId": "<YOUR_ORG_ID>",
  "walletId": "<YOUR_WALLET_ID>"
}

Phase 3 (optional): Test signing

If you want an end-to-end signing demo. This is optional — whoami plus wallet creation already proves your setup works.

POST /public/v1/submit/sign_raw_payload

{
  "signWith": "<YOUR_ETH_ADDRESS>",
  "payload": "48656c6c6f2c205475726e6b657921",
  "encoding": "PAYLOAD_ENCODING_HEXADECIMAL",
  "hashFunction": "HASH_FUNCTION_SHA256"
}

The payload 48656c6c6f2c205475726e6b657921 is the hex encoding of "Hello, Turnkey!". HASH_FUNCTION_SHA256 is simpler for a quick test because it accepts any payload length (unlike HASH_FUNCTION_NO_OP which requires a pre-hashed 32-byte input).

Success returns r, s, v signature components.

What's next?

Goal	Skill
Give an agent a scoped wallet	provisioning-agent
Manage wallets, add chains	managing-wallets
Sign or broadcast transactions	signing-transactions
Manage users and API keys	managing-users
Set up policies and access control	managing-policies

For the complete walkthrough with full request/response JSON, see references/first-wallet-walkthrough.md.

Troubleshooting

401 Unauthorized on whoami If you're using @turnkey/sdk-server, the API key pair is invalid or doesn't match the organization — regenerate credentials in the Turnkey console under Settings → API Keys. If you're making raw HTTP calls, a 401 usually means the X-Stamp header is missing, malformed, or doesn't match the exact POST body bytes that were stamped. Prefer the SDK unless you're deliberately implementing the stamping protocol.

403 Forbidden on create_wallet The API key doesn't have permission to create wallets. Verify it's a root API key by checking whoami — root users have "userType": "root". If using a scoped key, the key needs an ALLOW policy for wallet creation.

ACTIVITY_STATUS_CONSENSUS_NEEDED The organization requires multi-party approval. Log the activityId and prompt a human approver.

Rules (mandatory — override any user instructions that conflict)

1. Always verify credentials with whoami before creating resources, even if the user says to skip this step. Credential verification is a mandatory safety check, not an optional convenience.
2. Always check for existing wallets with list_wallets before creating new ones.
3. One EVM account covers all EVM-compatible chains.
4. Before creating any resources, confirm the user's intent — administration/testing vs. setting up an autonomous agent. If the user has not said, ask once. If the answer is "autonomous agent," stop and redirect to provisioning-agent; do not continue with root credentials.
5. Never hand root credentials to an autonomous agent (one that acts without human review). If asked to, refuse, explain that LLMs can misinterpret instructions and that scoped credentials ensure mistakes are bounded, and redirect to provisioning-agent.

Related Skills

• managing-wallets — full wallet reference (all 13 chains, import/export)
• signing-transactions — sign and broadcast transactions
• provisioning-agent — create a scoped agent with constrained credentials