Initiate wallet pairing (or restore code)
import requests
url = "https://api.example.com/api/v1/wallets/pairs/initiate"
payload = { "wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.example.com/api/v1/wallets/pairs/initiate \
--header 'Content-Type: application/json' \
--data '
{
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'{
"result": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"claimer_principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"token": "<string>",
"status": "pending",
"token_purpose": "pair",
"expires_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"pair_link": "<string>",
"agent": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"external_id": "<string>"
},
"wallet": {
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"wallet_type": "Custodial",
"name": "<string>",
"status": "preparing"
}
},
"success": true,
"suggestion": "",
"message": "",
"meta": {
"total": 123,
"offset": 123,
"limit": 123,
"has_more": true,
"after": "<string>",
"before": "<string>"
}
}{
"result": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"claimer_principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"token": "<string>",
"status": "pending",
"token_purpose": "pair",
"expires_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"pair_link": "<string>",
"agent": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"external_id": "<string>"
},
"wallet": {
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"wallet_type": "Custodial",
"name": "<string>",
"status": "preparing"
}
},
"success": true,
"suggestion": "",
"message": "",
"meta": {
"total": 123,
"offset": 123,
"limit": 123,
"has_more": true,
"after": "<string>",
"before": "<string>"
}
}{
"success": false,
"error": {
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}
}Wallets
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.POST
/
api
/
v1
/
wallets
/
pairs
/
initiate
Initiate wallet pairing (or restore code)
import requests
url = "https://api.example.com/api/v1/wallets/pairs/initiate"
payload = { "wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a" }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.example.com/api/v1/wallets/pairs/initiate \
--header 'Content-Type: application/json' \
--data '
{
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'{
"result": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"claimer_principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"token": "<string>",
"status": "pending",
"token_purpose": "pair",
"expires_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"pair_link": "<string>",
"agent": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"external_id": "<string>"
},
"wallet": {
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"wallet_type": "Custodial",
"name": "<string>",
"status": "preparing"
}
},
"success": true,
"suggestion": "",
"message": "",
"meta": {
"total": 123,
"offset": 123,
"limit": 123,
"has_more": true,
"after": "<string>",
"before": "<string>"
}
}{
"result": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"wallet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"claimer_principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_principal_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"token": "<string>",
"status": "pending",
"token_purpose": "pair",
"expires_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"pair_link": "<string>",
"agent": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"external_id": "<string>"
},
"wallet": {
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"wallet_type": "Custodial",
"name": "<string>",
"status": "preparing"
}
},
"success": true,
"suggestion": "",
"message": "",
"meta": {
"total": 123,
"offset": 123,
"limit": 123,
"has_more": true,
"after": "<string>",
"before": "<string>"
}
}{
"success": false,
"error": {
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}
}Headers
Body
application/json
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.
The ID of the wallet to pair.
Response
Already exists (idempotent). Successful Response
Wallet pairing initiate response payload.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes