Python SDK - Cobo Agentic Wallet

Overview

WalletAPIClient is an async Python client built on a generated OpenAPI SDK. It handles authentication, request routing, and response unwrapping across all API domains.

Basic usage

import asyncio
from cobo_agentic_wallet.client import WalletAPIClient

API_URL = "https://api.agenticwallet.cobo.com"
API_KEY = "your-api-key"
WALLET_UUID = "your-wallet-uuid"

async def main():
    async with WalletAPIClient(base_url=API_URL, api_key=API_KEY) as client:
        wallets = await client.list_wallets()

asyncio.run(main())

All methods are async. Use async with WalletAPIClient(...) as client: to ensure the HTTP session is closed cleanly.

Constructor

from cobo_agentic_wallet.client import WalletAPIClient

client = WalletAPIClient(
    base_url="https://api.agenticwallet.cobo.com",
    api_key="your-api-key",
    timeout=30.0,
)

base_url

str

required

API base URL (for example, https://api.agenticwallet.cobo.com).

api_key

str | None

default:"None"

X-API-Key header value for authentication. Required unless allow_unauthenticated=True.

allow_unauthenticated

bool

default:"False"

When True, allows requests without an API key. Use only for unauthenticated endpoints such as ping().

timeout

float

default:"30.0"

Request timeout in seconds.

service_auth_key

str | None

default:"None"

Service credential for admin-only operations such as create_principal().

Context manager

async with WalletAPIClient(base_url="...", api_key="...") as client:
    wallets = await client.list_wallets()

The context manager automatically closes the underlying HTTP client on exit.

Health methods

`ping()`

Ping the API. No authentication required.

`health_check()`

Get detailed system health status.

Wallet methods

`list_wallets()`

List all wallets accessible to the authenticated principal.

offset

int | None

default:"0"

The number of items to skip before returning results. Range: [0, 100000].

limit

int | None

default:"50"

The maximum number of items to return. Range: [1, 200].

include_archived

bool | None

default:"False"

Whether to include archived wallets. True: include archived. False: exclude archived.

`get_wallet()`

Get detailed information about a specific wallet by its ID.

wallet_uuid

str

required

The wallet UUID. Retrieve it by calling list_wallets().

include_spend_summary

bool | None

default:"None"

When True, includes per-delegation spending summaries in the response.

`create_wallet()`

Create a new wallet. Wallet provisioning is asynchronous — the initial response returns status=preparing; the wallet transitions to status=active once key generation completes.

wallet_type

str

required

The wallet type. Use MPC.

name

str

required

The wallet name. Max 255 characters.

group_type

str | None

default:"None"

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.

main_node_id

str | None

default:"None"

The TSS node ID of the agent’s main device. Required when wallet_type=MPC.

metadata

dict | None

default:"None"

Arbitrary key-value metadata to associate with the wallet.

for_owner

bool | None

default:"False"

When True, creates the wallet on behalf of the principal’s linked owner. When False, the wallet is created for the principal itself.

`update_wallet()`

Update the name or metadata of a specific wallet.

wallet_uuid

str

required

The wallet UUID. Retrieve it by calling list_wallets().

wallet_update

Any

required

Update payload containing the fields to change.

`create_wallet_address()`

Derive a new on-chain address for the specified wallet and chain.

wallet_uuid

str

required

The wallet UUID. Retrieve it by calling list_wallets().

chain_type

str

required

The Cobo chain ID for the new address (for example, SETH, BASE_ETH, SOL). Use list_chains() to retrieve all supported chain IDs.

`list_wallet_addresses()`

List all on-chain addresses associated with a specific wallet.

wallet_uuid

str

required

The wallet UUID. Retrieve it by calling list_wallets().

`get_wallet_node_status()`

Get the online status of the TSS node associated with a specific wallet.

wallet_uuid

str

required

The wallet UUID. Retrieve it by calling list_wallets().

`initiate_wallet_pair()`

Initiate wallet ownership pairing and obtain a one-time pairing token for the user to enter in the Cobo Agentic Wallet app.

wallet_pair_initiate

Any

required

The wallet pair initiation payload. Must include the wallet UUID.

`confirm_wallet_pair()`

Confirm wallet ownership pairing after the user has entered the pairing token.

wallet_pair_confirm

Any

required

The wallet pair confirmation payload.

`get_pair_info()`

Get pairing info by a one-time pairing token.

token

str

required

The one-time pairing token.

`get_pair_info_by_wallet()`

Get pairing info by wallet UUID.

wallet_uuid

str

required

The wallet UUID.

`wallet_reshare()`

Initiate a TSS key reshare for the specified wallet.

wallet_uuid

str

required

The wallet UUID.

node_id

str

required

The new TSS node ID to reshare to.

`wallet_tss_callback()`

Report a TSS request callback result to the platform.

wallet_uuid

str

required

The wallet UUID.

tss_request_id

str

required

The TSS request ID.

status

int

required

The TSS request status code.

results

list | None

default:"None"

TSS result items.

failed_reasons

list[str] | None

default:"None"

Failure reason strings, if any.

Balance methods

`list_balances()`

List cached token balances across all wallets accessible to the authenticated principal. Balances are synchronized from on-chain data and may be slightly delayed.

wallet_uuid

str | None

default:"None"

Filter balances by wallet ID. Retrieve it by calling list_wallets().

chain_id

str | None

default:"None"

Filter balances by chain ID (for example, SETH, BASE_ETH).

address

str | None

default:"None"

Filter balances by on-chain address.

token_id

str | None

default:"None"

Filter balances by token ID (for example, SETH, SETH_USDC).

force_refresh

bool

default:"False"

When True and address is provided, forces a fresh sync of balances from on-chain before returning results.

limit

int | None

default:"50"

The maximum number of items to return. Range: [1, 200].

offset

int | None

default:"0"

The number of items to skip before returning results.

Transaction methods

`transfer_tokens()`

Initiate a token transfer from the specified wallet. Gas fees are covered automatically. Returns HTTP 202 with status=pending_approval when an approval policy requires human review.

wallet_uuid

str

required

The wallet UUID. Retrieve it by calling list_wallets().

dst_addr

str

required

The destination on-chain address.

amount

str

required

The transfer amount as a decimal string (for example, 1.5).

token_id

str | None

default:"SETH"

The Cobo token ID (for example, SETH, SETH_USDC, SOLDEV_SOL_USDC). Use list_assets() to retrieve all supported token IDs.

chain_id

str | None

default:"None"

The chain ID. Automatically resolved from token_id if omitted.

request_id

str | None

default:"None"

A client-supplied idempotency key. If a transfer with the same request_id already exists for this wallet and principal, the existing record is returned with idempotent=true.

fee

Any | None

default:"None"

Custom fee parameters. If omitted, the network default is used.

src_addr

str | None

default:"None"

The source address to transfer from. If omitted, the wallet’s most recently created address for this chain is used.

Whether to use Cobo Gasless (Fee Station) to cover gas fees. Defaults to True for human-owned wallets, False for agent-owned wallets.

gas_provider

str | None

default:"None"

Optional gas provider identifier when sponsored gas is supported.

description

str | None

default:"None"

A human-readable description of the transfer.

`estimate_transfer_fee()`

Estimate the network fee for a token transfer without submitting it. Returns recommended, slow, and fast fee options. Policy evaluation runs — an error is returned if a policy would deny the equivalent transfer.

wallet_uuid

str

required

The wallet UUID. Retrieve it by calling list_wallets().

dst_addr

str

required

The destination on-chain address.

amount

str

required

The transfer amount as a decimal string.

token_id

str | None

default:"SETH"

The Cobo token ID.

chain_id

str | None

default:"None"

The chain ID. Automatically resolved from token_id if omitted.

src_addr

str | None

default:"None"

The source address. If omitted, the wallet’s most recently created address for this chain is used.

`contract_call()`

Submit a smart contract call from the specified wallet. For EVM chains, provide contract_addr, value, and calldata. For Solana, provide instructions and optionally address_lookup_table_accounts. Returns HTTP 202 with status=pending_approval when an approval policy requires human review.

wallet_uuid

str

required

The wallet UUID. Retrieve it by calling list_wallets().

chain_id

str

required

The Cobo chain ID (for example, SETH, BASE_ETH, SOL).

contract_addr

str | None

default:"None"

The EVM contract address. Required for EVM contract calls.

value

str | None

default:"0"

The ETH value to send with the call, as a decimal string in the smallest unit. Defaults to 0.

calldata

str | None

default:"None"

The ABI-encoded calldata for EVM contract calls, as a hex string.

instructions

list | None

default:"None"

Solana instructions for the contract call. Required for Solana contract calls.

address_lookup_table_accounts

list | None

default:"None"

Solana address lookup table accounts.

request_id

str | None

default:"None"

A client-supplied idempotency key.

fee

Any | None

default:"None"

Custom fee parameters. If omitted, the network default is used.

src_addr

str | None

default:"None"

The source address. If omitted, the wallet’s most recently created address for this chain is used.

Whether to use Cobo Gasless to cover gas fees. Defaults to True for human-owned wallets, False for agent-owned wallets.

gas_provider

str | None

default:"None"

Optional gas provider identifier when sponsored gas is supported.

description

str | None

default:"None"

Optional human-readable description for auditability.

`estimate_contract_call_fee()`

Estimate the network fee for a contract call without submitting it. Policy evaluation runs — an error is returned if a policy would deny the equivalent call.

`drop_transaction()`

Attempt to cancel a pending transaction by replacing it with a zero-value transaction at a higher fee.

wallet_uuid

str

required

The wallet UUID.

transaction_uuid

str

required

The transaction UUID to drop. Retrieve it from the list_transaction_records() response.

request_id

str | None

default:"None"

A client-supplied idempotency key.

fee

Any | None

default:"None"

Custom fee to use for the replacement transaction.

cobo_transaction_id

str | None

default:"None"

The Cobo-internal transaction ID.

`speedup_transaction()`

Speed up a pending transaction by rebroadcasting it with a higher fee.

wallet_uuid

str

required

The wallet UUID.

transaction_uuid

str

required

The transaction UUID to speed up.

fee

Any | None

default:"None"

The new fee to use. Must be higher than the original.

request_id

str | None

default:"None"

A client-supplied idempotency key.

cobo_transaction_id

str | None

default:"None"

The Cobo-internal transaction ID.

`message_sign()`

Sign a message or EIP-712 typed data using the wallet’s key.

wallet_uuid

str

required

The wallet UUID.

chain_id

str

required

The Cobo chain ID.

destination_type

Any | None

default:"None"

The message destination type.

eip712_typed_data

dict | None

default:"None"

EIP-712 typed data to sign.

source_address

str | None

default:"None"

The source address to sign from.

description

str | None

default:"None"

A human-readable description of the signing request.

sync

bool | None

default:"True"

When True, waits for the signing result before returning. When False, returns immediately — poll via the transaction ID.

request_id

str | None

default:"None"

A client-supplied idempotency key.

`payment()`

Create a payment request. Supports the x402 and MPP protocols.

wallet_uuid

str

required

The wallet UUID.

protocol

Any | None

default:"None"

The payment protocol identifier.

request_id

str | None

default:"None"

A client-supplied idempotency key.

x402_payment_required

str | None

default:"None"

The raw PAYMENT-REQUIRED header value from an x402 server response.

mpp_www_authenticate

str | None

default:"None"

The WWW-Authenticate header value from an MPP server response.

mpp_session

Any | None

default:"None"

An existing MPP session object to resume.

`list_recent_addresses()`

List recently used destination addresses for a wallet.

wallet_uuid

str

required

The wallet UUID.

limit

int | None

default:"None"

The maximum number of addresses to return.

`handle_waas_webhook()`

Handle an incoming WaaS webhook event.

body

dict[str, Any]

required

The webhook request body as a parsed dict.

biz_timestamp

str | None

default:"None"

The business timestamp from the webhook header.

biz_resp_signature

str | None

default:"None"

The business response signature from the webhook header.

Transaction record methods

`list_transaction_records()`

List on-chain transaction records including transfers, contract calls, and deposits. When wallet_uuid is omitted, records across all wallets visible to the authenticated principal are returned.

wallet_uuid

str | None

default:"None"

Filter records by wallet ID. When omitted, records from all wallets are returned.

after

str | None

default:"None"

A cursor for forward pagination.

before

str | None

default:"None"

A cursor for backward pagination.

offset

int | None

default:"0"

The number of items to skip before returning results. Range: [0, 100000].

limit

int | None

default:"50"

The maximum number of items to return. Range: [1, 200].

status

str | None

default:"None"

Filter by transaction status. Possible values: created, submitted, broadcasting, success, failed, rejected. If omitted, all statuses are returned.

record_type

str | None

default:"None"

Filter by transaction type. Possible values: transfer, contract_call, deposit. If omitted, all types are returned.

token_id

str | None

default:"None"

Filter by token ID (for example, SETH, SETH_USDC).

chain_id

str | None

default:"None"

Filter by chain ID (for example, SETH, BASE_ETH).

address_id

str | None

default:"None"

Filter by on-chain address.

ext

bool | None

default:"None"

When True, includes extended fields in the response.

`get_transaction_record()`

Get a specific on-chain transaction record by its ID.

wallet_uuid

str

required

The wallet UUID.

record_uuid

str

required

The transaction record UUID. Retrieve it by calling list_transaction_records().

ext

bool | None

default:"None"

When True, includes extended fields in the response.

`get_transaction_record_by_request_id()`

Get a specific on-chain transaction record by client request ID.

wallet_uuid

str

required

The wallet UUID.

request_id

str

required

The client-supplied request ID used when submitting the transaction.

ext

bool | None

default:"None"

When True, includes extended fields in the response.

Delegation methods

`create_delegation()`

Grant an operator access to a wallet on behalf of the authenticated principal.

operator_id

str

required

The ID of the principal receiving wallet access.

wallet_id

str

required

The wallet to delegate access to. Retrieve it by calling list_wallets().

permissions

list[str]

required

The permissions to grant. Valid values: read:wallet, operator, write:wallet, write:transfer, write:contract_call.

policies

list | None

default:"None"

Optional delegation-scoped policies to create alongside the delegation.

expires_at

datetime | None

default:"None"

The expiry timestamp for this delegation. If omitted, the delegation does not expire.

`get_delegation()`

Get details of a specific delegation.

delegation_id

str

required

The delegation UUID. Retrieve it by calling list_delegations().

`list_delegations()`

List delegations created by the authenticated principal.

operator_id

str | None

default:"None"

Filter by operator ID.

wallet_id

str | None

default:"None"

Filter by wallet ID.

status

Any | None

default:"None"

Filter by status. Possible values: active, revoked, expired.

after

str | None

default:"None"

A cursor for forward pagination.

before

str | None

default:"None"

A cursor for backward pagination.

offset

int | None

default:"0"

The number of items to skip.

limit

int | None

default:"50"

The maximum number of items to return.

`list_received_delegations()`

List delegations received by the authenticated principal (where the principal is the operator).

`update_delegation()`

Update an existing delegation.

`revoke_delegation()`

Revoke an active delegation. Once revoked, the operator loses access to the wallet.

`freeze_delegations()`

Freeze one or more delegations, temporarily suspending the operator’s access.

scope

Any

required

The freeze scope. Controls which delegations are frozen.

owner_id

str | None

default:"None"

Freeze all delegations for this owner. Required when scope targets by owner.

wallet_id

str | None

default:"None"

Freeze all delegations on this wallet.

delegation_id

str | None

default:"None"

Freeze a specific delegation by ID.

reason

str | None

default:"None"

A human-readable reason for freezing.

`unfreeze_delegations()`

Unfreeze previously frozen delegations, restoring operator access. Parameters mirror freeze_delegations().

Policy methods

`create_policy()`

Create a new policy.

scope

Any

required

The policy scope. Possible values: global (applies to all wallets), wallet, delegation.

wallet_id

str | None

default:"None"

Required when scope=wallet or scope=delegation. Retrieve it by calling list_wallets().

delegation_id

str | None

default:"None"

Required when scope=delegation. Retrieve it by calling list_delegations().

name

str

required

The policy name. Max 255 characters.

policy_type

Any

required

The policy type. Possible values: transfer (governs token transfers), contract_call (governs smart contract calls).

rules

dict

required

The policy rule configuration as a JSON object. Structure depends on policy_type.

priority

int | None

default:"0"

The policy priority. Higher values take precedence when multiple policies match the same operation.

is_active

bool | None

default:"True"

Whether this policy is active. True: the policy is evaluated. False: the policy is disabled.

`get_policy()`

Get details of a specific policy.

`list_policies()`

List all policies for the authenticated principal.

scope

Any | None

default:"None"

Filter by scope. Possible values: global, wallet, delegation.

wallet_id

str | None

default:"None"

Required when scope=wallet or scope=delegation.

delegation_id

str | None

default:"None"

Filter by delegation ID. Only applicable when scope=delegation.

policy_type

Any | None

default:"None"

Filter by policy type. Possible values: transfer, contract_call.

include_inactive

bool | None

default:"None"

When True, includes inactive policies in the results.

offset

int | None

default:"0"

The number of items to skip.

limit

int | None

default:"50"

The maximum number of items to return.

`update_policy()`

Update an existing policy.

`deactivate_policy()`

Deactivate a policy without deleting it. Deactivated policies are not evaluated.

`dry_run_policy()`

Simulate policy evaluation without executing any transaction. Returns whether the operation would be allowed or denied.

wallet_id

str

required

The wallet ID to evaluate policies against.

delegation_id

str | None

default:"None"

Optional delegation ID to evaluate within a specific delegation context.

operation_type

Any

required

The type of operation to simulate. Possible values: transfer, contract_call.

amount

str

required

The operation amount as a decimal string. For transfers, must be greater than zero.

chain_id

str

required

The Cobo chain ID (for example, SETH, BASE_ETH, SOL).

token_id

str | None

default:"None"

The Cobo token ID. Required for operation_type=transfer.

dst_addr

str | None

default:"None"

The destination address. Required for operation_type=transfer.

contract_addr

str | None

default:"None"

The EVM contract address. Required for operation_type=contract_call on EVM chains.

calldata

str | None

default:"None"

The ABI-encoded calldata for EVM contract calls, as a hex string.

instructions

list | None

default:"None"

Solana instructions. Required for operation_type=contract_call on Solana.

principal_id

str | None

default:"None"

Override the principal used for evaluation. Defaults to the authenticated principal.

Pending operation methods

`list_pending_operations()`

List pending operations awaiting human approval.

status

Any | None

default:"None"

Filter by pending operation status.

after

str | None

default:"None"

A cursor for forward pagination.

before

str | None

default:"None"

A cursor for backward pagination.

offset

int | None

default:"0"

The number of items to skip.

limit

int | None

default:"50"

The maximum number of items to return.

`get_pending_operation()`

Get details of a specific pending operation.

pending_operation_id

str

required

The pending operation ID.

`approve_pending_operation()`

Approve a pending operation, allowing it to proceed.

pending_operation_id

str

required

The pending operation ID.

`reject_pending_operation()`

Reject a pending operation.

pending_operation_id

str

required

The pending operation ID. Retrieve it from the transfer_tokens() or contract_call() response when status=pending_approval.

reason

str | None

default:"None"

A human-readable reason for rejection.

Approval methods

`get_approval()`

Get the current status and details of an approval request. Poll this to check for status=approved and retrieve the approval_result.

approval_id

str

required

The approval ID. Retrieve it by calling list_approvals().

`list_approvals()`

List approval requests for the authenticated human principal.

subject_type

Any | None

default:"None"

Filter approvals by subject type (for example, transaction, pact). If omitted, all types are returned.

status

Any | None

default:"None"

Filter approvals by status. If omitted, all statuses are returned.

after

str | None

default:"None"

A cursor for forward pagination. Pass the after value from a previous response to retrieve the next page.

before

str | None

default:"None"

A cursor for backward pagination. Pass the before value from a previous response to retrieve the preceding page.

offset

int | None

default:"None"

Deprecated. Use after/before cursors instead.

limit

int

default:"50"

The maximum number of items to return. Range: [1, 200].

`resolve_approval()`

Approve or reject a pending approval request. Only the wallet owner can resolve approvals.

approval_id

str

required

The approval ID. Retrieve it by calling list_approvals().

action

Any

required

The resolution action. Possible values: approve, reject.

response

Any | None

default:"None"

Optional response payload. May include a reason string (for rejections) and/or a revised_pact PactSpec object (for approvals that revise the pact before activation).

Pact methods

`submit_pact()`

Submit a pact specification for owner approval. The pact enters pending_approval status and a notification is sent to the Cobo Agentic Wallet app. The operator’s identity is resolved from the authenticated API key.

wallet_id

str

required

The wallet ID the pact will operate on.

intent

str

required

A natural-language description of what the agent intends to do (for example, "DCA $500/week into ETH on Base for 3 months"). Shown to the owner during approval.

spec

dict

required

The PactSpec object describing the requested scope, including permissions, policies, and completion conditions.

name

str | None

default:"None"

A short display name for the pact. If omitted, a name is derived from intent.

original_intent

str | None

default:"None"

The unmodified user request, before any agent reformulation. Used for audit purposes.

result = await client.submit_pact(
    wallet_id="a1b2c3d4-...",
    intent="DCA $500/week into ETH on Base for 3 months",
    spec={
        "permissions": ["write:contract_call", "read:wallet"],
        "policies": [...],
        "completion_conditions": [
            {"type": "time_elapsed", "threshold": "7776000"}
        ],
    }
)
pact_id = result["pact_id"]

Returns a dict with pact_id, status, and approval_id.

`get_pact()`

Get pact detail and trigger lazy activation. If the linked approval has been resolved since the last fetch, the pact transitions to active and the response includes api_key.

pact_id

str

required

The pact ID returned by submit_pact().

Returns a pact dict with fields including status, api_key (when active), delegation_id, wallet_id, and spec.

`list_pacts()`

List pacts visible to the authenticated principal. Agents see pacts they submitted; owners see pacts on wallets they own.

status

str | None

default:"None"

Filter by pact status. Possible values: pending_approval, active, revoked, expired.

wallet_id

str | None

default:"None"

Filter by wallet ID.

after

str | None

default:"None"

A cursor for forward pagination.

before

str | None

default:"None"

A cursor for backward pagination.

offset

int | None

default:"0"

The number of items to skip before returning results.

limit

int | None

default:"50"

The maximum number of items to return.

include_default

bool | None

default:"None"

When True, includes the default pact in results.

`list_pact_events()`

Get the lifecycle event history for a pact (for example, submitted, approved, activated, revoked).

pact_id

str

required

The pact ID. Retrieve it by calling submit_pact() or list_pacts().

after

str | None

default:"None"

A cursor for forward pagination.

before

str | None

default:"None"

A cursor for backward pagination.

offset

int | None

default:"None"

The number of items to skip before returning results.

limit

int | None

default:"None"

The maximum number of items to return.

`revoke_pact()`

Revoke an active pact. Only the wallet owner can revoke. This revokes the underlying delegation and invalidates the pact-scoped API key.

pact_id

str

required

The pact ID. Retrieve it by calling list_pacts().

Returns the updated pact dict with status=revoked.

`withdraw_pact()`

Withdraw a pending pact that has not yet been approved.

pact_id

str

required

The pact ID. Retrieve it by calling list_pacts().

`update_policies()`

Update the policies attached to an active pact.

pact_id

str

required

The pact ID.

policies

list | None

default:"None"

The new list of policy objects to apply.

`update_completion_conditions()`

Update the completion conditions for an active pact.

pact_id

str

required

The pact ID.

completion_conditions

list | None

default:"None"

The new list of completion condition objects.

Identity methods

`provision_agent()`

Provision an agent by creating an API key and binding it to an owner. Supply token to use the pairing code from the Cobo Agentic Wallet app. If token is omitted, provisioning runs in agent-first mode — the response contains a temporary activation_secret that the human uses to complete binding.

token

str | None

default:"None"

The pairing code from the Cobo Agentic Wallet app.

invitation_code

str | None

default:"None"

An alternative invitation code.

name

str | None

default:"None"

A display name for the agent.

`get_agent_status()`

Get the provisioning and activation status of a specific agent. Accepts either the internal UUID or the external ID.

`list_my_agents()`

List all agent principals owned by the authenticated principal.

after

str | None

default:"None"

A cursor for forward pagination.

before

str | None

default:"None"

A cursor for backward pagination.

offset

int | None

default:"None"

The number of items to skip.

limit

int | None

default:"None"

The maximum number of items to return.

`create_principal()`

Create a new principal (human or agent identity). Requires service credential authentication. If a principal with the same external_id already exists, the existing record is returned.

external_id

str

required

An external identifier for the principal, unique within your system.

principal_type

Any

required

The principal type. Possible values: human, agent.

name

str

required

A display name for the principal.

metadata

dict | None

default:"None"

Arbitrary key-value metadata to associate with the principal.

`list_principals()`

List all principals. Requires service credential authentication.

after

str | None

default:"None"

A cursor for forward pagination.

before

str | None

default:"None"

A cursor for backward pagination.

offset

int | None

default:"None"

The number of items to skip.

limit

int | None

default:"None"

The maximum number of items to return.

principal_type

Any | None

default:"None"

Filter by type. Possible values: human, agent.

`update_principal()`

Update a principal’s metadata or display name.

principal_id

str

required

The principal ID to update.

principal_update

Any

required

Update payload containing the fields to change.

`create_api_key()`

Create a new API key for a principal. When called with a principal API key, the key is created for the authenticated principal. When called with a service credential, principal_id is required.

The raw API key value is only returned once. Store it securely — it cannot be retrieved again.

principal_id

str | None

default:"None"

The principal to create the key for. Required when using a service credential.

name

str

required

A display name for the API key.

scopes

list[str] | None

default:"None"

Permission scopes for the key. Defaults to ["*"] (full access). Use resource:action format (for example, ["wallet:read", "wallet:write"]).

expires_at

datetime | None

default:"None"

Expiry time for the key. If omitted, the key does not expire.

`list_api_keys()`

List all API keys for the authenticated principal.

after

str | None

default:"None"

A cursor for forward pagination.

before

str | None

default:"None"

A cursor for backward pagination.

offset

int | None

default:"None"

The number of items to skip.

limit

int | None

default:"None"

The maximum number of items to return.

`revoke_api_key()`

Permanently revoke an API key. Once revoked, the key cannot be used for authentication.

api_key_id

str

required

The API key ID to revoke.

This action cannot be undone.

Audit methods

`list_audit_logs()`

Retrieve audit logs for the authenticated principal. Uses cursor-based pagination — pass next_cursor from the previous response as cursor to retrieve the next page.

wallet_id

str | None

default:"None"

Filter by wallet ID.

principal_id

str | None

default:"None"

Filter by the principal that performed the action.

action

str | None

default:"None"

Filter by action name (for example, transfer.initiate, delegation.create).

result

Any | None

default:"None"

Filter by result. Possible values: allowed, denied, pending, error.

start_time

datetime | None

default:"None"

Filter logs created at or after this timestamp (ISO 8601).

end_time

datetime | None

default:"None"

Filter logs created before this timestamp (ISO 8601).

cursor

str | None

default:"None"

Pagination cursor. Pass the next_cursor from a previous response.

limit

int

default:"50"

The maximum number of items to return. Range: [1, 200].

Metadata methods

`list_chains()`

List supported chains. Uses cursor-based pagination.

wallet_type

Any

required

The wallet type. Use MPC.

chain_ids

str | None

default:"None"

A comma-separated list of Cobo chain IDs to filter by (for example, SETH,BASE_ETH). If omitted, all chains are returned.

limit

int | None

default:"None"

The maximum number of items to return. Range: [1, 500].

before

str | None

default:"None"

A cursor for backward pagination. Pass the before value from a previous response to retrieve the preceding page.

after

str | None

default:"None"

A cursor for forward pagination. Pass the after value from a previous response to retrieve the next page.

`list_assets()`

List supported tokens (assets). Uses cursor-based pagination.

wallet_type

Any

required

The wallet type. Use MPC.

chain_ids

str | None

default:"None"

A comma-separated list of Cobo chain IDs to filter by (for example, SETH,BASE_ETH). If omitted, tokens for all chains are returned.

token_ids

str | None

default:"None"

A comma-separated list of token IDs to filter by (for example, SETH,SETH_USDC). If omitted, all tokens are returned.

limit

int | None

default:"None"

The maximum number of items to return. Range: [1, 500].

before

str | None

default:"None"

A cursor for backward pagination. Pass the before value from a previous response to retrieve the preceding page.

after

str | None

default:"None"

A cursor for forward pagination. Pass the after value from a previous response to retrieve the next page.

`get_chain_info_by_chain_id()`

Get detailed information about a specific chain by its Cobo chain ID.

chain_id

str

required

The Cobo chain ID (for example, SETH, BASE_ETH, SOL).

`search_tokens()`

Search for token candidates matching a symbol across supported chains.

symbol

str

required

The token symbol to search for (for example, USDC, ETH).

Faucet methods

`deposit()`

Request a test token deposit to a specified address. Only available on testnets.

address

str | None

default:"None"

The destination address to receive test tokens.

token_id

str | None

default:"None"

The token to request (for example, SETH_USDC). Use list_tokens() to see available tokens.

`list_tokens()`

List all tokens available from the faucet.

Coin price methods

`get_asset_coin_prices()`

Get current prices for one or more tokens.

asset_coins

str

required

Comma-separated Cobo token IDs (for example, SETH,SETH_USDC).

currency

str | None

default:"None"

The fiat currency for prices (for example, USD). Defaults to USD if omitted.

AP2 methods

`get_merchants()`

List AP2 merchants available to the authenticated principal.

Supported chains

Tools

SDK

Framework integrations

API Reference

​Overview

​Basic usage

​Constructor

​Context manager

​Health methods

​ping()

​health_check()

​Wallet methods

​list_wallets()

​get_wallet()

​create_wallet()

​update_wallet()

​create_wallet_address()

​list_wallet_addresses()

​get_wallet_node_status()

​initiate_wallet_pair()

​confirm_wallet_pair()

​get_pair_info()

​get_pair_info_by_wallet()

​wallet_reshare()

​wallet_tss_callback()

​Balance methods

​list_balances()

​Transaction methods

​transfer_tokens()

​estimate_transfer_fee()

​contract_call()

​estimate_contract_call_fee()

​drop_transaction()

​speedup_transaction()

​message_sign()

​payment()

​list_recent_addresses()

​handle_waas_webhook()

​Transaction record methods

​list_transaction_records()

​get_transaction_record()

​get_transaction_record_by_request_id()

​Delegation methods

​create_delegation()

​get_delegation()

​list_delegations()

​list_received_delegations()

​update_delegation()

​revoke_delegation()

​freeze_delegations()

​unfreeze_delegations()

​Policy methods

​create_policy()

​get_policy()

​list_policies()

​update_policy()

​deactivate_policy()

​dry_run_policy()

​Pending operation methods

​list_pending_operations()

​get_pending_operation()

​approve_pending_operation()

​reject_pending_operation()

​Approval methods

​get_approval()

​list_approvals()

​resolve_approval()

​Pact methods

​submit_pact()

​get_pact()

​list_pacts()

​list_pact_events()

​revoke_pact()

​withdraw_pact()

​update_policies()

​update_completion_conditions()

​Identity methods

​provision_agent()

​get_agent_status()

Overview

Basic usage

Constructor

Context manager

Health methods

`ping()`

`health_check()`

Wallet methods

`list_wallets()`

`get_wallet()`

`create_wallet()`

`update_wallet()`

`create_wallet_address()`

`list_wallet_addresses()`

`get_wallet_node_status()`

`initiate_wallet_pair()`

`confirm_wallet_pair()`

`get_pair_info()`

`get_pair_info_by_wallet()`

`wallet_reshare()`

`wallet_tss_callback()`

Balance methods

`list_balances()`

Transaction methods

`transfer_tokens()`

`estimate_transfer_fee()`

`contract_call()`

`estimate_contract_call_fee()`

`drop_transaction()`

`speedup_transaction()`

`message_sign()`

`payment()`

`list_recent_addresses()`

`handle_waas_webhook()`

Transaction record methods

`list_transaction_records()`

`get_transaction_record()`

`get_transaction_record_by_request_id()`

Delegation methods

`create_delegation()`

`get_delegation()`

`list_delegations()`

`list_received_delegations()`

`update_delegation()`

`revoke_delegation()`

`freeze_delegations()`

`unfreeze_delegations()`

Policy methods

`create_policy()`

`get_policy()`

`list_policies()`

`update_policy()`

`deactivate_policy()`

`dry_run_policy()`

Pending operation methods

`list_pending_operations()`

`get_pending_operation()`

`approve_pending_operation()`

`reject_pending_operation()`

Approval methods

`get_approval()`

`list_approvals()`

`resolve_approval()`

Pact methods

`submit_pact()`

`get_pact()`

`list_pacts()`

`list_pact_events()`

`revoke_pact()`

`withdraw_pact()`

`update_policies()`

`update_completion_conditions()`

Identity methods

`provision_agent()`

`get_agent_status()`

`list_my_agents()`

`create_principal()`

`list_principals()`

`update_principal()`

`create_api_key()`