> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/products/agentic-wallet/manual/llms.txt
> Use this file to discover all available pages before exploring further.
# Create wallet
> This operation creates a new wallet for the authenticated principal.
You need to provide `name` and `main_node_id` (the agent's TSS node ID).
Set `group_type` to control the MPC key share scheme:
- `agent` (2-of-2): Agent TSS node + Cobo. Default for agent-controlled wallets.
- `human` (2-of-2): Mobile TSS node + Cobo.
Set `for_owner=true` to create the wallet on behalf of the principal's linked owner. If no linked owner exists, the wallet is created for the principal itself. Defaults to `false`.
Wallet provisioning is asynchronous. The initial response returns `status=preparing`; the wallet transitions to `status=active` once key generation completes.
## OpenAPI
````yaml post /api/v1/wallets
openapi: 3.1.0
info:
title: Cobo Agentic Wallet Service
description: Unified wallet engine for human and agent principals
version: 1.3.0
servers: []
security: []
paths:
/api/v1/wallets:
post:
tags:
- Wallets
summary: Create wallet
description: >-
This operation creates a new wallet for the authenticated principal.
You need to provide `name` and `main_node_id` (the agent's TSS node ID).
Set `group_type` to control the MPC key share scheme:
- `agent` (2-of-2): Agent TSS node + Cobo. Default for agent-controlled
wallets.
- `human` (2-of-2): Mobile TSS node + Cobo.
Set `for_owner=true` to create the wallet on behalf of the principal's
linked owner. If no linked owner exists, the wallet is created for the
principal itself. Defaults to `false`.
Wallet provisioning is asynchronous. The initial response returns
`status=preparing`; the wallet transitions to `status=active` once key
generation completes.
operationId: create_wallet
parameters:
- name: X-API-Key
in: header
required: false
schema:
title: X-Api-Key
type: string
nullable: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WalletCreate'
responses:
'200':
description: Already exists (idempotent). Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse_WalletRead_'
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse_WalletRead_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/WrappedValidationError'
components:
schemas:
WalletCreate:
properties:
wallet_type:
$ref: '#/components/schemas/WalletType'
description: The wallet type. Use `MPC`.
name:
type: string
maxLength: 255
minLength: 1
title: Name
description: The wallet name. Max 255 characters.
group_type:
$ref: '#/components/schemas/VaultGroupType'
description: >-
The MPC key share scheme. `AGENT` (2-of-2): agent TSS node + Cobo,
suitable for automated wallets. `HUMAN` (2-of-2): mobile TSS node +
Cobo, suitable for human-controlled wallets. Defaults to `AGENT`.
default: agent
main_node_id:
title: Main Node Id
description: >-
The TSS node ID of the agent's main device. Required when
`wallet_type=MPC`.
type: string
nullable: true
metadata:
additionalProperties: true
type: object
title: Metadata
description: Arbitrary key-value metadata to associate with the wallet.
for_owner:
type: boolean
title: For Owner
description: >-
Whether to create the wallet for the principal's linked owner
(`true`) or for the principal itself (`false`). Defaults to `false`.
default: false
type: object
required:
- wallet_type
- name
title: WalletCreate
description: |-
Request payload for creating a wallet.
Ownership can be selected via `for_owner`:
- for_owner=False: create for current principal (Agent)
- for_owner=True: create for current principal's owner (Human),
or fallback to current principal when no owner is linked
StandardResponse_WalletRead_:
properties:
success:
type: boolean
title: Success
default: true
result:
$ref: '#/components/schemas/WalletRead'
suggestion:
type: string
title: Suggestion
default: ''
message:
type: string
title: Message
default: ''
meta:
$ref: '#/components/schemas/PaginationMeta'
nullable: true
type: object
required:
- result
title: StandardResponse[WalletRead]
WrappedValidationError:
title: WrappedValidationError
type: object
required:
- success
- error
properties:
success:
type: boolean
const: false
default: false
title: Success
error:
type: object
title: Error
required:
- detail
properties:
detail:
type: array
title: Detail
items:
$ref: '#/components/schemas/ValidationError'
WalletType:
type: string
enum:
- Custodial
- MPC
title: WalletType
description: Supported wallet types.
VaultGroupType:
type: string
enum:
- agent
- human
title: VaultGroupType
description: |-
MPC Vault Group 类型
均为 2/2 配置 (User 1 片 + Cobo 1 片)。
AGENT: Agent 持有密钥分片，用于服务端自动签名（CLI 发起）
HUMAN: Human 持有密钥分片，用于 UCW 移动端签名（Mobile App 发起）
当 Agent 钱包被 Human 认领后，同一个 Wallet 会同时拥有 AGENT 和 HUMAN
两个 VaultGroup，分别对应不同的签名参与方。
WalletRead:
properties:
uuid:
type: string
format: uuid
title: Uuid
description: The wallet ID.
wallet_type:
$ref: '#/components/schemas/WalletType'
description: The wallet type (for example, `MPC`).
name:
type: string
title: Name
description: The wallet name.
owner_id:
type: string
format: uuid
title: Owner Id
description: The ID of the principal that owns this wallet.
cobo_wallet_id:
title: Cobo Wallet Id
description: The wallet ID assigned by Cobo WaaS.
type: string
nullable: true
status:
$ref: '#/components/schemas/WalletStatus'
description: >-
The wallet status. Possible values: `preparing`, `active`,
`archived`.
metadata:
additionalProperties: true
type: object
title: Metadata
description: Arbitrary key-value metadata associated with the wallet.
created_at:
type: string
format: date-time
title: Created At
description: The timestamp when the wallet was created, in ISO 8601 format.
updated_at:
type: string
format: date-time
title: Updated At
description: The timestamp when the wallet was last updated, in ISO 8601 format.
main_node_id:
title: Main Node Id
description: >-
TSS node ID of the wallet owner's main device. Only set for MPC
wallets.
type: string
nullable: true
type: object
required:
- uuid
- wallet_type
- name
- owner_id
- cobo_wallet_id
- status
- metadata
- created_at
- updated_at
title: WalletRead
description: Wallet response payload.
PaginationMeta:
properties:
total:
title: Total
type: integer
nullable: true
offset:
title: Offset
type: integer
nullable: true
limit:
title: Limit
type: integer
nullable: true
has_more:
title: Has More
type: boolean
nullable: true
after:
title: After
type: string
nullable: true
before:
title: Before
type: string
nullable: true
type: object
title: PaginationMeta
description: |-
Pagination metadata for list responses.
Supports both legacy offset-based and cursor-based pagination.
Cursor fields (``has_more``, ``after``, ``before``) are populated for
cursor-paginated endpoints. Legacy fields (``offset``, ``limit``) are
populated when the caller uses the deprecated ``offset`` parameter.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
WalletStatus:
type: string
enum:
- preparing
- active
- archived
title: WalletStatus
description: Supported wallet statuses.
````