Skip to content
GRYPHEM PAYGRYPHEM PAYGRYPHEM PAY Docs

Register a watch-only or simulated wallet

POST
/v1/wallets
curl --request POST \
  --url https://api.feitpay.com/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Gryphem-Environment: test' \
  --data '{ "store_id": "example", "network_id": "example", "label": "example", "mode": "simulated", "xpub": "example", "gap_limit": 20 }'

Accepts an extended public key (xpub mode) — never a seed phrase or private key. Honors Idempotency-Key (replays return the original response for 24 h).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Gryphem-Organization
string

Active organization for dashboard sessions. Ignored for API keys (the key determines the organization).

Gryphem-Environment
string
default: test
Allowed values: test live

test (default) or live for dashboard sessions. API keys determine the environment.

Idempotency-Key
string
<= 255 characters

Unique key per logical create operation (max 255 chars). Replays return the original response; reuse with a different body returns idempotency_error.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
store_id
required
string
network_id
required
string
label
required
string
>= 1 characters <= 80 characters
mode
required
string
Allowed values: simulated xpub
xpub

Extended PUBLIC key: a BIP84 account key (xpub/zpub) for Bitcoin, or the account-level key for EVM (m/44’/60’/0’) and TRON (m/44’/195’/0’). Never send private keys.

string
<= 200 characters
gap_limit
integer
default: 20 >= 1 <= 1000

Responses

Section titled “Responses”

201

Section titled “201”

Registered (watch-only).

Media typeapplication/json
object
id
required
string
object
required
string
Allowed value: wallet
livemode
required
boolean
store_id
required
string
network_id
required
string
label
required
string
mode
required
string
Allowed values: simulated xpub
address_type
required
string
Allowed values: p2wpkh evm tron simulated
xpub_fingerprint
required
string | null
derivation_template
required
string | null
status
required
string
Allowed values: active disabled
next_index
required
integer
gap_limit
required
integer
last_used_index
required
integer | null
ownership
required
object
status
required
string
Allowed values: unverified pending verified failed expired sandbox_fixture
verified_at
required
string | null format: date-time
created_at
required
string format: date-time

Example 

{
  "object": "wallet",
  "mode": "simulated",
  "address_type": "p2wpkh",
  "status": "active",
  "ownership": {
    "status": "unverified"
  }
}

401

Section titled “401”

Missing or invalid credentials.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error
code
required
string
message
required
string
param
string
request_id
required
string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}

403

Section titled “403”

The feature is not available for your account: the account is not activated yet, the network or payment method is not enabled, or a required partner is not in place.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error
code
required
string
message
required
string
param
string
request_id
required
string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}

409

Section titled “409”

State conflict.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error
code
required
string
message
required
string
param
string
request_id
required
string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}

422

Section titled “422”

Validation failed.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error
code
required
string
message
required
string
param
string
request_id
required
string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}

429

Section titled “429”

Too many requests. See Retry-After.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error idempotency_error rate_limit_error feature_unavailable_error api_error
code
required
string
message
required
string
param
string
request_id
required
string

Example 

{
  "error": {
    "type": "invalid_request_error"
  }
}

Headers

Section titled “Headers”
Retry-After
integer