import cobo_waas2
from cobo_waas2.models.create_satoshi_test_challenge_request import (
    CreateSatoshiTestChallengeRequest,
)
from cobo_waas2.models.satoshi_test_challenge import SatoshiTestChallenge
from cobo_waas2.rest import ApiException
from pprint import pprint

# See configuration.py for a list of all supported configurations.
configuration = cobo_waas2.Configuration(
    # Replace `<YOUR_PRIVATE_KEY>` with your private key
    api_private_key="<YOUR_PRIVATE_KEY>",
    # Select the development environment. To use the production environment, change the URL to https://api.cobo.com/v2.
    host="https://api.dev.cobo.com/v2",
)
# Enter a context with an instance of the API client
with cobo_waas2.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = cobo_waas2.TravelRuleApi(api_client)
    create_satoshi_test_challenge_request = (
        cobo_waas2.CreateSatoshiTestChallengeRequest()
    )

    try:
        # Create Satoshi Test challenge
        api_response = api_instance.create_satoshi_test_challenge(
            create_satoshi_test_challenge_request=create_satoshi_test_challenge_request
        )
        print("The response of TravelRuleApi->create_satoshi_test_challenge:\n")
        pprint(api_response)
    except Exception as e:
        print(
            "Exception when calling TravelRuleApi->create_satoshi_test_challenge: %s\n"
            % e
        )

{
  "challenge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "from_address": "0x1234567890abcdef1234567890abcdef12345678",
  "to_address": "0xabcdef1234567890abcdef1234567890abcdef12",
  "amount": "1100001000000000",
  "token_id": "ETH",
  "chain_id": "ETH",
  "status": "PENDING",
  "remaining_seconds": 10550,
  "matched_txid": "0xabc123...",
  "started_at": 1732523887000,
  "expires_at": 1732534687000
}

Travel Rule operations

Create Satoshi Test challenge

This operation creates a Satoshi Test challenge for self-custody address verification. Satoshi Test verifies address ownership by having the counterparty transfer a small, uniquely-generated amount from their wallet to a Cobo-controlled verification address.

A single endpoint covers both flows via the action parameter:

Two-step flow (action=PREPARE then action=SUBMIT): Preview the verification details first, then activate. The 180-minute countdown only starts on SUBMIT. The server uses (chain_id, from_address) as the idempotency key, so the second call automatically targets the prepared challenge. For extra safety, pass the challenge_id returned by PREPARE in the subsequent SUBMIT call — it pins the activation to that specific challenge.
One-shot flow (action=SUBMIT directly, without challenge_id): Prepare and submit in a single call. The challenge is created directly in PENDING state with the countdown started.

If the counterparty address has already been verified, the operation returns HTTP 400 ADDRESS_ALREADY_VERIFIED. Call List address verifications with chain_id, address, and status=VERIFIED first to pre-check.

Supported chains: BTC, ETH, BASE_ETH, BSC_BNB, TRON.

POST

travel_rule

satoshi_test

challenge

import cobo_waas2
from cobo_waas2.models.create_satoshi_test_challenge_request import (
    CreateSatoshiTestChallengeRequest,
)
from cobo_waas2.models.satoshi_test_challenge import SatoshiTestChallenge
from cobo_waas2.rest import ApiException
from pprint import pprint

# See configuration.py for a list of all supported configurations.
configuration = cobo_waas2.Configuration(
    # Replace `<YOUR_PRIVATE_KEY>` with your private key
    api_private_key="<YOUR_PRIVATE_KEY>",
    # Select the development environment. To use the production environment, change the URL to https://api.cobo.com/v2.
    host="https://api.dev.cobo.com/v2",
)
# Enter a context with an instance of the API client
with cobo_waas2.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = cobo_waas2.TravelRuleApi(api_client)
    create_satoshi_test_challenge_request = (
        cobo_waas2.CreateSatoshiTestChallengeRequest()
    )

    try:
        # Create Satoshi Test challenge
        api_response = api_instance.create_satoshi_test_challenge(
            create_satoshi_test_challenge_request=create_satoshi_test_challenge_request
        )
        print("The response of TravelRuleApi->create_satoshi_test_challenge:\n")
        pprint(api_response)
    except Exception as e:
        print(
            "Exception when calling TravelRuleApi->create_satoshi_test_challenge: %s\n"
            % e
        )

{
  "challenge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "from_address": "0x1234567890abcdef1234567890abcdef12345678",
  "to_address": "0xabcdef1234567890abcdef1234567890abcdef12",
  "amount": "1100001000000000",
  "token_id": "ETH",
  "chain_id": "ETH",
  "status": "PENDING",
  "remaining_seconds": 10550,
  "matched_txid": "0xabc123...",
  "started_at": 1732523887000,
  "expires_at": 1732534687000
}

Try Cobo WaaS Skill in your AI coding assistant (Claude Code, Cursor, etc.). Describe your needs in natural language to auto-generate production-ready SDK code and debug faster 🚀

import cobo_waas2
from cobo_waas2.models.create_satoshi_test_challenge_request import (
    CreateSatoshiTestChallengeRequest,
)
from cobo_waas2.models.satoshi_test_challenge import SatoshiTestChallenge
from cobo_waas2.rest import ApiException
from pprint import pprint

# See configuration.py for a list of all supported configurations.
configuration = cobo_waas2.Configuration(
    # Replace `<YOUR_PRIVATE_KEY>` with your private key
    api_private_key="<YOUR_PRIVATE_KEY>",
    # Select the development environment. To use the production environment, change the URL to https://api.cobo.com/v2.
    host="https://api.dev.cobo.com/v2",
)
# Enter a context with an instance of the API client
with cobo_waas2.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = cobo_waas2.TravelRuleApi(api_client)
    create_satoshi_test_challenge_request = (
        cobo_waas2.CreateSatoshiTestChallengeRequest()
    )

    try:
        # Create Satoshi Test challenge
        api_response = api_instance.create_satoshi_test_challenge(
            create_satoshi_test_challenge_request=create_satoshi_test_challenge_request
        )
        print("The response of TravelRuleApi->create_satoshi_test_challenge:\n")
        pprint(api_response)
    except Exception as e:
        print(
            "Exception when calling TravelRuleApi->create_satoshi_test_challenge: %s\n"
            % e
        )

Authorizations

BIZ-API-KEY

string

header

required

The API key. For more details, refer to API key.

In the API playground, enter your API secret, and your API key will be accordingly calculated.

Body

application/json

Request body for creating a Satoshi Test challenge. A single endpoint covers both the two-step flow (PREPARE then SUBMIT) and the one-shot flow (SUBMIT directly). Idempotent on (chain_id, from_address) per organization.

action

enum<string>

required

The action to perform when creating a Satoshi Test challenge.

PREPARE: Preview the verification address and amount. The 180-minute countdown is NOT started yet. Repeated PREPARE calls for the same (chain_id, from_address) refresh the amount.
SUBMIT: Activate the challenge and start the 180-minute countdown. If a PREPARE challenge already exists for this (chain_id, from_address) it is activated; otherwise a new challenge is created directly in PENDING state (one-shot flow).

Available options:

PREPARE,

SUBMIT

Example:

"PREPARE"

chain_id

string

required

The chain ID of the counterparty address. See the operation description for supported chains.

Example:

"ETH"

from_address

string

required

The counterparty (self-custody) wallet address that will transfer the micro-deposit.

Example:

"0x1234567890abcdef1234567890abcdef12345678"

transaction_id

string<uuid>

required

The Cobo transaction ID that this Satoshi Test is verifying for.

Example:

"123e4567-e89b-12d3-a456-426614174000"

transaction_type

enum<string>

required

The direction of the underlying transaction in a Travel Rule operation.

DEPOSIT: A deposit transaction (verifying the source address).
WITHDRAW: A withdrawal transaction (verifying the destination address).

Available options:

DEPOSIT,

WITHDRAW

Example:

"DEPOSIT"

challenge_id

string<uuid>

The challenge_id returned by a previous PREPARE call.

When action=SUBMIT: if provided, activates that specific challenge by id (recommended when you cached the id client-side after PREPARE). If omitted, the server activates the latest matching challenge identified by (chain_id, from_address).
When action=PREPARE: must be omitted. A new challenge is always generated; passing a challenge_id here will cause the request to be rejected.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Response

The Satoshi Test challenge was created.

action=PREPARE: returned challenge has status=PREPARE; the 180-minute countdown is not started yet.
action=SUBMIT: returned challenge has status=PENDING; started_at and expires_at are set.

If the counterparty address has already been verified (by signature or a prior Satoshi Test), this operation returns HTTP 400 ADDRESS_ALREADY_VERIFIED instead — call List address verifications with chain_id, address, and status=VERIFIED first to pre-check.

Full information about a Satoshi Test challenge, returned by the create and get operations.

challenge_id

string<uuid>

required

The unique identifier of the Satoshi Test challenge.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

from_address

string

required

The counterparty (self-custody) wallet address that must transfer the micro-deposit.

Example:

"0x1234567890abcdef1234567890abcdef12345678"

to_address

string

required

The Cobo-generated verification address that will receive the micro-deposit.

Example:

"0xabcdef1234567890abcdef1234567890abcdef12"

amount

string

required

The exact amount (in the token's smallest unit) that must be transferred. The amount is unique per challenge and is used together with to_address to identify a matching on-chain transfer.

Example:

"1100001000000000"

token_id

string

required

The ID of the token used for the micro-deposit (typically the chain's native asset).

Example:

"ETH"

chain_id

string

required

The chain on which the micro-deposit is expected.

Example:

"ETH"

status

enum<string>

required

The lifecycle status of a Satoshi Test challenge.

PREPARE: Challenge created (address and amount returned); the 180-minute countdown is not started yet.
PENDING: Challenge submitted; countdown active, waiting for the counterparty's on-chain transfer.
MATCHED: An on-chain transfer matching the expected amount has been observed; waiting for block confirmations.
VERIFIED: The matched transfer reached confirmation — the address is verified.
EXPIRED: Challenge was not matched within 180 minutes.
DELETED: Challenge was cancelled by the client.

Available options:

PREPARE,

PENDING,

MATCHED,

VERIFIED,

EXPIRED,

DELETED

Example:

"PENDING"

remaining_seconds

integer

required

Remaining time (in seconds) before the challenge expires. 0 when the challenge is not yet submitted or has already completed/expired.

Example:

10550

matched_txid

string | null

The on-chain transaction hash of the matching transfer, once matched.

Example:

"0xabc123..."

started_at

integer<int64> | null

Timestamp (milliseconds) when the challenge was submitted and the countdown started.

Example:

1732523887000

expires_at

integer<int64> | null

Timestamp (milliseconds) when the challenge will expire if not matched.

Example:

1732534687000

Get self-custody signature challenge Get Satoshi Test challenge

⌘I

Documentation Index

Authorizations

Body

Response