> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zodia-custody.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding with Claude Code

> Use Claude Code to guide yourself through your first Zodia API integration, step by step.

Zodia's API documentation is designed to be machine-readable and fully
compatible with [Claude Code](https://claude.ai/code) — Anthropic's
AI-powered command-line coding assistant.

If you are integrating with the Zodia API for the first time, you can
install the Zodia onboarding skill to guide yourself through the process
interactively, one step at a time, directly from your terminal.

## Prerequisites

Before you begin, make sure you have:

<Steps>
  <Step title="A Zodia account with sandbox access">
    If you do not have sandbox access enabled, contact your Zodia
    account manager before proceeding. Do not attempt Stage 1 without it.
  </Step>

  <Step title="Claude Code installed">
    Install Claude Code by following the
    [official installation guide](https://docs.anthropic.com/en/docs/claude-code).
  </Step>
</Steps>

## Install the Zodia Onboarding Skill

The recommended installation method adds the Zodia onboarding skill
as a Claude Code slash command. This works globally across all your
projects and does not affect any existing `CLAUDE.md` files.

Run this command in your terminal:

```bash theme={null}
mkdir -p ~/.claude/commands && curl -o ~/.claude/commands/zodia-onboard.md \
https://raw.githubusercontent.com/scv-lydia/zodia-api-docs-mintlify-implementation/main/claude-code/zodia-onboard.md
```

Then start Claude Code from any directory:

```bash theme={null}
claude
```

And invoke the skill with:

/zodia-onboard

<AccordionGroup>
  <Accordion title="I already have a CLAUDE.md file in my project">
    Use the slash command installation above. It installs the Zodia
    onboarding skill globally under `~/.claude/commands/` and does not
    touch your existing `CLAUDE.md`. You can then run `/zodia-onboard`
    from any directory without any conflict.
  </Accordion>

  <Accordion title="I don't have a CLAUDE.md file and prefer to use one">
    If you would rather use a project-level `CLAUDE.md`, save the skill
    file directly into your working directory:

    ```bash theme={null}
        curl -o CLAUDE.md \
        https://raw.githubusercontent.com/scv-lydia/zodia-api-docs-mintlify-implementation/main/claude-code/zodia-onboard.md
    ```

    Claude Code will detect it automatically when you run `claude` from
    that directory. Note that if you already have a `CLAUDE.md`, this
    will overwrite it.
  </Accordion>
</AccordionGroup>

## What the Skill Does

Once invoked, the skill configures Claude Code to:

* Walk you through four onboarding stages, one step at a time
* Reference Zodia's API documentation as its primary source
* Ask for credentials and inputs only when needed
* Guide you to use the interactive **Try it** feature in these docs
  wherever possible
* Produce a session summary so you can pick up where you left off

## Onboarding Stages

| Stage | Name                 | Maker required | Checker required |
| ----- | -------------------- | :------------: | :--------------: |
| 1     | Authentication       |        ✓       |                  |
| 2     | Read wallet balances |        ✓       |                  |
| 3     | Create a wallet      |        ✓       |         ✓        |
| 4     | Transfer funds       |        ✓       |         ✓        |

<Info>
  A **maker** initiates an action. A **checker** approves it.
  These must be two separate Zodia user accounts. Claude Code will
  remind you of this at the relevant stages.
</Info>

### Stage 3 in detail — wallet creation is a 7-step flow

Creating a wallet involves more steps than most API integrations. Claude
Code will guide you through all seven, but it helps to know the shape of
the flow before you start:

| Step | Endpoint                     | Who                                        |
| ---- | ---------------------------- | ------------------------------------------ |
| 1    | `POST /servicedesk/products` | Retrieve the wallet product template       |
| 2    | `POST /servicedesk/create`   | Maker creates the request → **DRAFT**      |
| 3    | `POST /servicedesk/submit`   | Maker submits it → signing workflow begins |
| 4    | `POST /servicedesk/pending`  | Maker retrieves their HSM instruction      |
| 5    | `POST /servicedesk/approve`  | Maker signs with their ECC key             |
| 6    | `POST /servicedesk/pending`  | Checker retrieves their HSM instruction    |
| 7    | `POST /servicedesk/approve`  | Checker signs with their ECC key           |

<Warning>
  Steps 4–7 are time-sensitive. The signing instruction expires within a
  short window after it is issued. Complete the maker signing (steps 4–5)
  and checker signing (steps 6–7) promptly — do not leave the session
  idle between steps.
</Warning>

## Resuming a Session

At the end of each session, Claude Code will output a structured
**session summary**. To resume, start a new Claude Code session and
run `/zodia-onboard`, then paste your session summary when prompted.
Claude Code will pick up exactly where you left off.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The /zodia-onboard command isn't appearing">
    Make sure the skill file was saved to `~/.claude/commands/zodia-onboard.md`.
    Check with:

    ```bash theme={null}
        cat ~/.claude/commands/zodia-onboard.md
    ```

    If the file is missing, re-run the install command above.
  </Accordion>

  <Accordion title="I don't have sandbox access">
    Contact your Zodia account manager to request sandbox access
    before starting. Claude Code will not be able to complete
    Stage 1 without it.
  </Accordion>

  <Accordion title="Claude Code stopped and said the documentation doesn't cover a step">
    Note down the step and contact
    [Zodia support](https://zodia-custody.com) with the details.
    Do not attempt to work around it — the stop is intentional.
  </Accordion>

  <Accordion title="I need to use code instead of Try it">
    Just tell Claude Code — it will switch to providing curl or
    Python examples for any step where you prefer to work in code.
  </Accordion>

  <Accordion title="My wallet creation request is stuck in DRAFT">
    DRAFT means the request was created but not yet submitted. The
    `/create` endpoint alone is not enough — you must also call
    `/submit` to move the request into the signing workflow. If you
    skipped this step, re-run from `/submit` with the same `requestId`.
    Do not create a new request.
  </Accordion>

  <Accordion title="The /pending endpoint returns an empty response">
    An empty response means there is no instruction waiting for the
    user identified by `submitter-id`. Common causes:

    * The signing instruction has **expired** — re-run the full maker
      flow from `/create` to generate a fresh request and sign promptly
    * You are calling with the **wrong account** — steps 4–5 require the
      maker's `submitter-id`; steps 6–7 require the checker's
    * A previous `/submit` is still in progress — wait a few seconds
      and retry
  </Accordion>

  <Accordion title="I get error ER-1201 Invalid notification Id on /approve">
    This means the `intentId` inside the pending instruction has expired
    or does not match the request being approved. The most common cause
    is approving a request that was created in a previous session — the
    notification TTL has passed. Re-run the full maker flow to generate
    a fresh request and complete all signing steps in the same session.
  </Accordion>
</AccordionGroup>

## Once you're onboarded

This skill is designed for first-time integration only. Once you have
completed all four stages, see the **AI Operations Guide** for a
separate Claude Code skill designed for ongoing use — troubleshooting
errors, checking request status, and common operational tasks.

## Reference

* **Sandbox documentation:** [https://api-docs-qa.zodia-custody.com/](https://api-docs-qa.zodia-custody.com/)
* **Production documentation:** [https://docs.zodia-custody.com/](https://docs.zodia-custody.com/)
* **Skill file source:**
  [zodia-onboard.md on GitHub](https://github.com/scv-lydia/zodia-api-docs-mintlify-implementation/blob/main/claude-code/zodia-onboard.md)