transfer

Transfer satoshis from a Spark wallet to another Spark address.

POST /v1/wallets/{wallet_id}/rpc

curl --request POST \

  --url https://api.privy.io/v1/wallets/{wallet_id}/rpc \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
  "method": "transfer",
  "network": "MAINNET",
  "params": {
    "receiver_spark_address": "spark1pgss8z35rpycv4duqdk5u3sclhjnztjunv5yajlwk69tyv5fsvwwe9mgwmxfkx",
    "amount_sats": 16
  }
}'

200

{
  "method": "transfer",
  "data": {
    "id": "01983eb7-4008-7b73-b269-c0bd86955a1b",
    "sender_identity_public_key": "027bca218b2853d5ff2e9b174370f58107a23df98a759e968c523253c1702dd485",
    "receiver_identity_public_key": "038a3418498655bc036d4e4618fde5312e5c9b284ecbeeb68ab23289831cec9768",
    "status": "TRANSFER_STATUS_SENDER_KEY_TWEAKED",
    "total_value": 16,
    "expiry_time": "1970-01-01T00:00:00.000Z",
    "leaves": [
      {
        "leaf": {
          "id": "01983e38-b2f8-7649-a910-b2be1424de1d",
          "tree_id": "01983e36-e645-7a34-ab95-a6faec210992",
          "value": 16,
          "parent_node_id": "01983e38-b2e2-7edd-9b6b-a784545aa28c",
          "node_tx": "<hex-encoded-tx>",
          "refund_tx": "<hex-encoded-refund>",
          "vout": 0,
          "verifying_public_key": "<pubkey>",
          "owner_identity_public_key": "<pubkey>",
          "signing_keyshare": {
            "owner_identifiers": ["...", "..."],
            "threshold": 2,
            "public_key": "<pubkey>",
            "public_shares": {
              "...": "<pubkey>",
              "...": "<pubkey>"
            },
            "updated_time": "2025-07-24T23:14:14.598Z"
          },
          "status": "TRANSFER_LOCKED",
          "network": "MAINNET"
        },
        "secret_cipher": "<ciphertext>",
        "signature": "<hex>",
        "intermediate_refund_tx": "<hex>"
      }
    ],
    "created_time": "2025-07-24T23:14:14.276Z",
    "updated_time": "2025-07-24T23:14:14.618Z",
    "type": "TRANSFER",
    "transfer_direction": "OUTGOING",
    "encoding": "hex"
  }
}

Idempotency on errors: On 4xx or 5xx, Privy caches the response and replays it for the same key. Generate a new key to retry after a server error. Policy violations are an exception and allow same-key retries.

curl --request POST \

  --url https://api.privy.io/v1/wallets/{wallet_id}/rpc \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
  "method": "transfer",
  "network": "MAINNET",
  "params": {
    "receiver_spark_address": "spark1pgss8z35rpycv4duqdk5u3sclhjnztjunv5yajlwk69tyv5fsvwwe9mgwmxfkx",
    "amount_sats": 16
  }
}'

200

{
  "method": "transfer",
  "data": {
    "id": "01983eb7-4008-7b73-b269-c0bd86955a1b",
    "sender_identity_public_key": "027bca218b2853d5ff2e9b174370f58107a23df98a759e968c523253c1702dd485",
    "receiver_identity_public_key": "038a3418498655bc036d4e4618fde5312e5c9b284ecbeeb68ab23289831cec9768",
    "status": "TRANSFER_STATUS_SENDER_KEY_TWEAKED",
    "total_value": 16,
    "expiry_time": "1970-01-01T00:00:00.000Z",
    "leaves": [
      {
        "leaf": {
          "id": "01983e38-b2f8-7649-a910-b2be1424de1d",
          "tree_id": "01983e36-e645-7a34-ab95-a6faec210992",
          "value": 16,
          "parent_node_id": "01983e38-b2e2-7edd-9b6b-a784545aa28c",
          "node_tx": "<hex-encoded-tx>",
          "refund_tx": "<hex-encoded-refund>",
          "vout": 0,
          "verifying_public_key": "<pubkey>",
          "owner_identity_public_key": "<pubkey>",
          "signing_keyshare": {
            "owner_identifiers": ["...", "..."],
            "threshold": 2,
            "public_key": "<pubkey>",
            "public_shares": {
              "...": "<pubkey>",
              "...": "<pubkey>"
            },
            "updated_time": "2025-07-24T23:14:14.598Z"
          },
          "status": "TRANSFER_LOCKED",
          "network": "MAINNET"
        },
        "secret_cipher": "<ciphertext>",
        "signature": "<hex>",
        "intermediate_refund_tx": "<hex>"
      }
    ],
    "created_time": "2025-07-24T23:14:14.276Z",
    "updated_time": "2025-07-24T23:14:14.618Z",
    "type": "TRANSFER",
    "transfer_direction": "OUTGOING",
    "encoding": "hex"
  }
}

Headers

privy-app-id · string · required

ID of your Privy app.

privy-authorization-signature · string

Request authorization signature. If multiple signatures are required, they should be comma separated.

privy-request-expiry · string

Request expiry. Value is a Unix timestamp in milliseconds representing the deadline by which the request must be processed.

Path Parameters

wallet_id · string · required

ID of the wallet to get.

These wallet methods are modeled after the Spark Wallet SDK. For more information about this wallet method, check out the Spark Wallet documentation.

Body

method · string · required

Available options: transfer

network · string · required

Available options: MAINNET, REGTEST

params · object · required

Hide child attributes

receiver_spark_address · string · required

The Spark address of the recipient.

amount_sats · number · required

The amount to send in satoshis.

Returns

method · enum<string> · required

Available options: transfer

data · object · required

The returned Transfer object

Hide child attributes

id · string · required

sender_identity_public_key · string · required

receiver_identity_public_key · string · required

status · string · required

total_value · number · required

expiry_time · string

leaves · array<object> · required

Each item contains transfer metadata and encrypted leaf information.

Hide child attributes

leaf · object · required

Hide child attributes

id · string · required

tree_id · string · required

value · number · required

parent_node_id · string · required

node_tx · string · required

refund_tx · string · required

vout · number · required

verifying_public_key · string · required

owner_identity_public_key · string · required

signing_keyshare · object · required

Hide child attributes

owner_identifiers · array<string> · required

threshold · number · required

public_key · string · required

public_shares · object · required

A mapping from signer identifier to public share

updated_time · string · required

status · string · required

network · string · required

secret_cipher · string · required

signature · string · required

intermediate_refund_tx · string · required

created_time · string

updated_time · string

type · string

transfer_direction · string

encoding · string