Sign in

v1

latestOpenAPI 3.0.02026-07-24103118224.7 KB
Connect Transfers

Create an internal Connect transfer

Moves custodial funds from the authenticated marketplace to one of its sub-merchants. Only the MARKETPLACE → SUB_MERCHANT direction is allowed: originId MUST be the authenticated marketplace and destinationId MUST be a sub-merchant it owns. The amount is debited from the marketplace custodial wallet and credited to the sub-merchant custodial wallet on Base.

Privy-custodial origins settle synchronously (CONFIRMED). Bridge-custodial origins are submitted asynchronously (PROCESSING) and confirmed later via webhook. Provide an idempotencyKey to safely retry without double-spending.

post/api/connect/transfers

Request body

originIdstring required

User id of the account to debit. MUST be the authenticated marketplace account.

destinationIdstring required

User id of the account to credit. MUST be a sub-merchant owned by the authenticated marketplace.

amountInCentsnumber required

Amount to transfer, in minor units (cents). Must be a positive integer.

currency'USDC' | 'EURC'

Stablecoin to move. Defaults to USDC.

idempotencyKeystring

Caller-supplied idempotency key. Re-sending the same key returns the existing transfer instead of creating a duplicate.

descriptionstring

Free-form description stored on the transfer record.

metadataobject

Arbitrary metadata attached to the transfer.

Example request

{
  "originId": "usr_marketplace",
  "destinationId": "usr_submerchant",
  "amountInCents": 5000,
  "idempotencyKey": "transfer-2026-06-12-001",
  "description": "Weekly payout to seller Alpha"
}

Response

Transfer created

idstring required
marketplaceUserIdstring required
originUserIdstring required
destinationUserIdstring required
amountInCentsnumber required
currency'USDC' | 'EURC' required
status'INITIATED' | 'PROCESSING' | 'CONFIRMED' | 'FAILED' required

CONFIRMED is terminal-success. PROCESSING means the on-chain transfer was submitted and is awaiting confirmation (Bridge origins). FAILED is terminal-failure.

provider'privy' | 'bridge' required
referencestring nullable
txHashstring nullable
failReasonstring nullable
descriptionstring nullable
metadataobject nullable
createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "id": "clz0marketplacetransferid",
  "marketplaceUserId": "usr_marketplace",
  "originUserId": "usr_origin",
  "destinationUserId": "usr_destination",
  "amountInCents": 5000,
  "currency": "USDC",
  "status": "PROCESSING",
  "provider": "privy",
  "reference": "mkttransfer_clz0marketplacetransferid",
  "txHash": "0xabc...",
  "failReason": "ERROR",
  "description": "Weekly payout to seller Alpha",
  "createdAt": "2026-06-12T12:00:00.000Z",
  "updatedAt": "2026-06-12T12:00:05.000Z"
}