# Getting Started

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

- **Type:** Skill
- **Install:** `agentstack add skill-tkhq-turnkey-agent-skills-getting-started`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tkhq](https://agentstack.voostack.com/s/tkhq)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [tkhq](https://github.com/tkhq)
- **Source:** https://github.com/tkhq/turnkey-agent-skills/tree/main/skills/getting-started

## Install

```sh
agentstack add skill-tkhq-turnkey-agent-skills-getting-started
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`](../../SKILL.md#calling-the-api) 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

```env
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:

```bash
npm install @turnkey/sdk-server
```

```typescript
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": "", "organizationId": "", "parameters": {...}}`. Query endpoints (`whoami`, `list_wallets`, `list_wallet_accounts`) do not need the envelope. See the root [`SKILL.md`](../../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
```

```json
{
  "organizationId": ""
}
```

**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
```

```json
{
  "organizationId": ""
}
```

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
```

```json
{
  "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
```

```json
{
  "organizationId": "",
  "walletId": ""
}
```

## 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
```

```json
{
  "signWith": "",
  "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](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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tkhq](https://github.com/tkhq)
- **Source:** [tkhq/turnkey-agent-skills](https://github.com/tkhq/turnkey-agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tkhq-turnkey-agent-skills-getting-started
- Seller: https://agentstack.voostack.com/s/tkhq
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.