> ## 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.
# Initiate wallet pairing (or restore code)
> Only the **agent** (API key) calls this. The server sets **token_purpose** in the response.
• If this agent does not yet have a `pair`+`completed` claim for the wallet, the agent must **own** the wallet; a `pair` code is issued for human claim/confirm.
• After that first pair is complete, the same **agent** can call again to mint/rotate a `restore` code (e.g. human may already be owner).
Codes expire after 30 minutes. Re-calling this rotates the single pending `pair` or pending `restore` row (per wallet+agent) and invalidates the previous code.
## OpenAPI
````yaml post /api/v1/wallets/pairs/initiate
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/pairs/initiate:
post:
tags:
- Wallets
summary: Initiate wallet pairing (or restore code)
description: >-
Only the **agent** (API key) calls this. The server sets
**token_purpose** in the response.
• If this agent does not yet have a `pair`+`completed` claim for the
wallet, the agent must **own** the wallet; a `pair` code is issued for
human claim/confirm.
• After that first pair is complete, the same **agent** can call again
to mint/rotate a `restore` code (e.g. human may already be owner).
Codes expire after 30 minutes. Re-calling this rotates the single
pending `pair` or pending `restore` row (per wallet+agent) and
invalidates the previous code.
operationId: initiate_wallet_pair
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/WalletPairInitiate'
responses:
'200':
description: Already exists (idempotent). Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse_WalletPairInitiateRead_'
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse_WalletPairInitiateRead_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/WrappedValidationError'
components:
schemas:
WalletPairInitiate:
properties:
wallet_id:
type: string
format: uuid
title: Wallet Id
description: The ID of the wallet to pair.
type: object
required:
- wallet_id
title: WalletPairInitiate
description: >-
Request payload for Initiate wallet pairing (agent-only).
The server returns ``token_purpose=pair`` (before the first pair claim
is ``completed``) or
``token_purpose=restore`` (after it is ``completed``). Both variants
live on the same
``wallet_claims`` row set.
StandardResponse_WalletPairInitiateRead_:
properties:
success:
type: boolean
title: Success
default: true
result:
$ref: '#/components/schemas/WalletPairInitiateRead'
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[WalletPairInitiateRead]
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'
WalletPairInitiateRead:
properties:
id:
type: string
format: uuid
title: Id
description: The pairing record ID.
wallet_id:
type: string
format: uuid
title: Wallet Id
description: The wallet being paired.
claimer_principal_id:
title: Claimer Principal Id
description: >-
The ID of the principal who completed pairing. Null if not yet
completed.
type: string
format: uuid
nullable: true
agent_principal_id:
type: string
format: uuid
title: Agent Principal Id
description: The ID of the agent principal that initiated pairing.
token:
type: string
title: Token
description: The 8-digit numeric code used to authorize pairing.
status:
$ref: '#/components/schemas/WalletPairStatus'
description: >-
The pairing status. Possible values: `pending`, `paired`,
`completed`.
token_purpose:
$ref: '#/components/schemas/WalletPairTokenPurpose'
description: >-
`pair` = initial claim flow; `restore` = post-completion recovery
code.
expires_at:
type: string
format: date-time
title: Expires At
description: The timestamp when the pairing token expires, in ISO 8601 format.
created_at:
type: string
format: date-time
title: Created At
description: >-
The timestamp when the pairing record was created, in ISO 8601
format.
updated_at:
type: string
format: date-time
title: Updated At
description: >-
The timestamp when the pairing record was last updated, in ISO 8601
format.
agent:
$ref: '#/components/schemas/WalletPairAgentInfo'
description: >-
The agent principal that initiated pairing. Included on initiate and
confirm responses.
nullable: true
wallet:
$ref: '#/components/schemas/WalletPairWalletInfo'
description: The wallet being paired. Included on initiate and confirm responses.
nullable: true
pair_link:
type: string
title: Pair Link
description: >-
Pair page link in the Cobo Agentic Wallet app, formatted as
{WEB_CONSOLE_HOST}/wallet/pair?token=xxxx
type: object
required:
- id
- wallet_id
- claimer_principal_id
- agent_principal_id
- token
- status
- token_purpose
- expires_at
- created_at
- updated_at
- pair_link
title: WalletPairInitiateRead
description: Wallet pairing initiate 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
WalletPairStatus:
type: string
enum:
- pending
- paired
- completed
title: WalletPairStatus
description: Wallet pairing lifecycle statuses.
WalletPairTokenPurpose:
type: string
enum:
- pair
- restore
title: WalletPairTokenPurpose
description: >-
Which flow this claim row represents (pair claim vs post-completion
restore).
WalletPairAgentInfo:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
external_id:
type: string
title: External Id
type: object
required:
- id
- name
- external_id
title: WalletPairAgentInfo
description: Agent principal summary for pair info.
WalletPairWalletInfo:
properties:
uuid:
type: string
format: uuid
title: Uuid
wallet_type:
$ref: '#/components/schemas/WalletType'
name:
type: string
title: Name
status:
$ref: '#/components/schemas/WalletStatus'
type: object
required:
- uuid
- wallet_type
- name
- status
title: WalletPairWalletInfo
description: Wallet summary for pair info.
WalletType:
type: string
enum:
- Custodial
- MPC
title: WalletType
description: Supported wallet types.
WalletStatus:
type: string
enum:
- preparing
- active
- archived
title: WalletStatus
description: Supported wallet statuses.
````