# SSS Intent Kit Guide for AI Agents

Use this guide when a user wants an AI agent, wallet, or bot to build a cross-route trading plan on SSS.

## Scope

Intent Kit v1 is preview/build-only. It can validate structured intents, preview route plans, and build user-reviewable execution steps across ICP-route deposits, SSS internal swaps, and Ethereum withdrawal plans.

Intent Kit v1 cannot execute deposits, swaps, or withdrawals by itself. The output is a plan. Users or wallets must still sign real actions through the appropriate SSS execution surface.

## Required Safety Rules

1. Do not send natural language directly to SSS core as an execution instruction.
2. Convert the user goal into a structured `IntentRequestV1` first.
3. Always call `intent_validate_v1` or at least `intent_preview_v1` before presenting a route.
4. Always show blockers, warnings, pool id, route id, receiver, fee, min receive, and high-risk flags.
5. Do not guess an Ethereum receiver address.
6. Do not guess a route id or pool id if multiple choices exist.
7. Do not auto-submit Ethereum withdrawals from Intent Kit v1.
8. Treat `intent_build_steps_v1` output as a plan, not execution authority.
9. If `next_action` is `ManualReviewRequired`, stop and ask the user to review the route before continuing.
10. For caller-owned self-account swaps, use Agent Kit only after the user or operator has approved the action and the caller owns the relevant SSS internal balance.

## Recommended Workflow

1. Read `intent-manifest.json` and the public core Candid interface.
2. Call `intent_get_supported_assets_v1`.
3. Call `intent_get_supported_routes_v1`.
4. Convert the user goal into structured fields:
   - `intent_type`;
   - `owner`;
   - source location / asset / amount;
   - target location / asset / receiver;
   - slippage and min receive constraints;
   - `client_request_id`;
   - optional `pool_id`, `source_route_id`, or `withdraw_route_id`.
5. Call `intent_validate_v1`.
6. Call `intent_preview_v1`.
7. Present the preview to the user.
8. Call `intent_build_steps_v1` only after the user wants a concrete plan.
9. Let the wallet or user sign each real action separately.

## Example Intents

### Internal swap

User: "Swap 1 USDC to USDT inside SSS."

Plan:
- source: `SssInternal`, `USDC`, `1000000`;
- target: `SssInternal`, `USDT`;
- intent type: `InternalSwap`;
- expected build step: core `swap` call.

### ICP-route deposit then swap

User: "Use my ICP wallet ckUSDC and convert it to SSS USDT."

Plan:
- source: `IcpWallet`, `ckUSDC`;
- target: `SssInternal`, `USDT`;
- intent type: `DepositThenSwap`;
- expected build steps: deposit route action plus internal swap step.

### Internal swap then Ethereum withdrawal plan

User: "Convert my SSS USDC to Ethereum USDT."

Plan:
- source: `SssInternal`, `USDC`;
- target: `EthereumWallet`, `USDT`, receiver must be supplied;
- intent type: `SwapThenWithdrawPlan`;
- expected build steps: internal swap step plus high-risk Ethereum withdrawal plan.

## Integration acceptance checklist

Before exposing Intent Kit to users, an integration should pass these checks:

1. Discovery: call `intent_get_supported_assets_v1()` and `intent_get_supported_routes_v1()`.
2. Validation: reject missing `client_request_id`, unsupported assets, zero amount, missing Ethereum receiver, unsafe partial fill, and ambiguous route choices.
3. Preview: call `intent_preview_v1()` and display estimated receive, min receive, fee, pool id, route id, warnings, blockers, high-risk flags, and `next_action`.
4. Build: call `intent_build_steps_v1()` only after the user accepts the preview.
5. Step review: display canister, method, amount, receiver, `candid_args_text`, and `user_must_review` before any signature.
6. Withdrawal safety: never auto-submit Ethereum withdrawals. Run the existing live route/source check immediately before any submit path.
7. Receipt: use `intent_get_status_schema_v1()` and store your own `intent_id`, `client_request_id`, step results, tx refs, warnings, blockers, and final status.

Repository smoke command:

```bash
bash scripts/ops/intent_kit/smoke_intent_kit_v1.sh
```

The smoke script uses anonymous query calls by default and writes logs under `logs/intent_kit/`.

## Cross-route build-only example

For a full build-only route such as ICP wallet ckUSDC -> SSS USDC -> SSS USDT -> Ethereum USDT withdrawal plan, use:

- https://docs.sssdefi.ai/ai/openclaw-skill/examples/intent-cross-route-plan.candid

This example is intentionally high-risk and build-only. If the preview returns `WITHDRAW_GATE_BLOCKED`, `ManualReviewRequired`, or `RePreviewRequired`, stop automatic execution and show the blocker to the user.

## Links

- Intent Kit docs: https://docs.sssdefi.ai/intent-kit
- Intent manifest: https://docs.sssdefi.ai/intent-manifest.json
- Agent Kit docs: https://docs.sssdefi.ai/ai-agent-kit
- Core Candid: https://a4gq6-oaaaa-aaaab-qaa4q-cai.raw.icp0.io/?id=dlhkk-raaaa-aaaak-qyl5a-cai

## Status and receipt schema

Use `intent_get_status_schema_v1()` to retrieve the stateless lifecycle vocabulary for Intent Kit integrations.

Intent Kit v1 does not persist intent status in core stable state. Wallets, bots, and AI agents should keep their own `intent_id`, `client_request_id`, step results, warnings, blockers, and transaction references. Recommended statuses include `Draft`, `Previewed`, `StepsBuilt`, `WaitingForUserSignature`, `WaitingForDeposit`, `DepositDetected`, `SwapReady`, `SwapExecuted`, `WithdrawStepBuilt`, `WithdrawSubmitted`, `WithdrawConfirmed`, `ManualReviewRequired`, `Failed`, `Expired`, and `Cancelled`.

For withdrawal routes, keep `WithdrawStepBuilt` and `ManualReviewRequired` as high-risk states. Always re-run the live withdraw route/source check before any submit path.