curl --request POST \
--url https://dev.api.withconvexity.com/v1/wallet/transaction \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"fromAddress": 12,
"toAddress": "0x2222222222222222222222222222222222222222",
"amount": "150.00",
"chainType": "EVM",
"chainId": 8453,
"network": "MAINNET",
"cNGN": true,
"webhookUrl": "https://example.com/hooks/wallet",
"webhookSecret": "a-secret-you-generate-and-keep"
}
'{
"status": true,
"message": "Transfer submitted successfully",
"data": {
"id": "9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"type": "TRANSFER",
"chainType": "EVM",
"network": "MAINNET",
"chainId": 8453,
"signerType": "BUSINESS_HD",
"fromAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
"addressIndex": 12,
"toAddress": "0x2222222222222222222222222222222222222222",
"amount": "150.00",
"valueUsd": "150.00",
"tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"data": null,
"value": null,
"txHash": "0x9d8c7b6a5e4f3c2b1a0987654321fedcba9876543210abcdef1234567890abcd",
"status": "COMPLETED",
"gasUsed": "70152",
"feeWei": "12030000000000",
"explorerUrl": "https://basescan.org",
"explorerTxUrl": "https://basescan.org/tx/0x9d8c7b6a5e4f3c2b1a0987654321fedcba9876543210abcdef1234567890abcd",
"createdAt": "2026-07-03T08:14:02.771Z",
"updatedAt": "2026-07-03T08:14:09.010Z"
}
}Initiate transfer
Submits a token (or native) transfer from a derived wallet. Asynchronous by default: the request is validated, recorded, and answered 202 with the PENDING transaction while the on-chain execution continues. Poll Get transaction by id or pass webhookUrl to be notified of the outcome (see Transfer lifecycle). Pass waitForCompletion: true for the legacy synchronous mode, which holds the request open (typically 3–30s) and answers 201 (completed) or 422 (failed). On EVM testnets gas can be sponsored; on mainnet gas is debited from the business USD balance. Requires the wallet.transfer.create capability and an Idempotency-Key header. See Idempotency.
curl --request POST \
--url https://dev.api.withconvexity.com/v1/wallet/transaction \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"fromAddress": 12,
"toAddress": "0x2222222222222222222222222222222222222222",
"amount": "150.00",
"chainType": "EVM",
"chainId": 8453,
"network": "MAINNET",
"cNGN": true,
"webhookUrl": "https://example.com/hooks/wallet",
"webhookSecret": "a-secret-you-generate-and-keep"
}
'{
"status": true,
"message": "Transfer submitted successfully",
"data": {
"id": "9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"type": "TRANSFER",
"chainType": "EVM",
"network": "MAINNET",
"chainId": 8453,
"signerType": "BUSINESS_HD",
"fromAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
"addressIndex": 12,
"toAddress": "0x2222222222222222222222222222222222222222",
"amount": "150.00",
"valueUsd": "150.00",
"tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"data": null,
"value": null,
"txHash": "0x9d8c7b6a5e4f3c2b1a0987654321fedcba9876543210abcdef1234567890abcd",
"status": "COMPLETED",
"gasUsed": "70152",
"feeWei": "12030000000000",
"explorerUrl": "https://basescan.org",
"explorerTxUrl": "https://basescan.org/tx/0x9d8c7b6a5e4f3c2b1a0987654321fedcba9876543210abcdef1234567890abcd",
"createdAt": "2026-07-03T08:14:02.771Z",
"updatedAt": "2026-07-03T08:14:09.010Z"
}
}Authorizations
OAuth 2.0 access token from Auth-Edge.
Headers
Unique client-generated key (use a UUID) that makes this request safe to retry. A retry sent with the same key returns the original result instead of submitting again. See Idempotency.
Body
Sending wallet: either a complete wallet address (e.g. 0x71C7…976F) or its HD addressIndex (e.g. 12).
Recipient address.
Amount in the token's major unit, as a decimal string (e.g. "150.00" for 150 USDC).
EVM, SOLANA Target chain id. Use 84532 (Base Sepolia) for sponsored testnet transfers. Required for EVM.
ERC-20 token contract. Omit for a native transfer.
Optional. Set to true to transfer cNGN. Defaults to false.
Optional. true = legacy synchronous mode: hold the request open for the final outcome (201/422) instead of 202 + poll. Defaults to false.
Optional. POST the final transaction here once execution settles (wallet.transfer.completed / wallet.transfer.failed). HTTPS only in production; private/internal hosts rejected. Delivery is signed and retried. See Outcome webhook.
2048Optional (requires webhookUrl). Your own HMAC key for the webhook signature: verify deliveries with the value you sent. Held in memory only; never persisted or logged.
16 - 256Response
Created
The response is of type object.