latestOpenAPI 3.0.32026-08-20146131.7 MB

672b1916ba61

Payments

Execute transfer (custody)

Executes a transfer using server-side custody signing. The source walletId must reference a wallet from /v1/wallets. Private-transfer requests are provider-built, signed by SDP-controlled wallets when required, and submitted on the configured Solana cluster. Supply an Idempotency-Key to retry safely: an identical resolved request returns the original transfer, while reusing the key for a different request returns 409.

post/v1/payments/transfers

Headers

x-project-idstring

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Example:prj_example

Selects the active project for this request. Required for session/dashboard callers. Ignored when authenticating with an API key, whose scope is fixed to the key's project.

Idempotency-Keystring

Idempotency key for safely retrying mutating requests. 1-255 printable ASCII characters; echoed back on the response.

Example:idempotency_example_12345

Idempotency key for safely retrying mutating requests. 1-255 printable ASCII characters; echoed back on the response.

Request body

projectIdstring

Project identifier for the transfer context.

sourcestring required

Source wallet — the walletId field returned by GET /v1/wallets. The wallet record id and the public key are not accepted.

destinationstring required

Destination wallet address.

tokenstring required

Token to transfer. Pass SOL for the native token, a well-known token symbol (e.g. USDC) resolved to the configured cluster's mint, or a base58 SPL mint address. Custom tokens must be specified by their on-chain mint.

amountstring required

Token amount in UI units (decimal string).

memostring

Optional memo for the transfer.

Example request

{
  "projectId": "prj_example",
  "source": "privy_wallet_123",
  "destination": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "100.00",
  "privateTransfer": {
    "provider": "magicblock",
    "magicBlock": {
      "initIfMissing": true,
      "initAtasIfMissing": true,
      "maxDelayMs": "1000"
    }
  }
}

Response

Transfer executed

Example response

{
  "data": {
    "transfer": {
      "id": "xfr_example",
      "organizationId": "org_example",
      "walletId": "privy_wallet_123",
      "projectId": "prj_example",
      "type": "transfer",
      "direction": "outbound",
      "status": "confirmed",
      "signature": "sig_example",
      "serializedTx": "base64_tx_example",
      "slot": 123456,
      "blockTime": "2025-01-01T00:00:00.000Z",
      "fee": 5000,
      "error": "Signature failed",
      "initiatedBy": {
        "type": "api_key"
      },
      "source": "So11111111111111111111111111111111111111112",
      "destination": "So11111111111111111111111111111111111111112",
      "rampsMemo": {
        "invoice": "INV-123",
        "po": "PO-9"
      },
      "amount": "100.00",
      "provider": "moonpay",
      "counterpartyId": "counterparty_example",
      "counterpartyDisplayName": "Acme Studio",
      "providerReference": "ramp_quote_example",
      "deliveryMode": "session_widget",
      "fiatCurrency": "USD",
      "fiatAmount": "100.00",
      "risk": {
        "provider": "trm",
        "score": "0.12",
        "level": "low",
        "evaluatedAt": "2025-01-01T00:00:00.000Z"
      },
      "moneygram": {
        "transactionId": "mgi_tx_example",
        "referenceNumber": "12345678",
        "payoutAmount": 25,
        "payoutStatus": "completed",
        "cryptoTransferId": "xfr_moneygram_crypto_leg_example",
        "solanaTxSignature": "sig_moneygram_usdc_transfer_example",
        "lastWidgetError": "Transaction cancelled by user"
      },
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-02T00:00:00.000Z"
    },
    "privateTransfer": {
      "provider": "magicblock",
      "magicBlock": {
        "kind": "transfer",
        "version": "v0",
        "instructionCount": 4,
        "requiredSigners": [
          "So11111111111111111111111111111111111111112"
        ],
        "validator": "So11111111111111111111111111111111111111112"
      }
    }
  },
  "meta": {
    "requestId": "req_example",
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}