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"
  }
}

Wallet

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.

POST

wallet

transaction

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

Authorization

string

header

required

OAuth 2.0 access token from Auth-Edge.

Headers

Idempotency-Key

string

required

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

application/json

fromAddress

required

Sending wallet: either a complete wallet address (e.g. 0x71C7…976F) or its HD addressIndex (e.g. 12).

toAddress

string

required

Recipient address.

amount

string

required

Amount in the token's major unit, as a decimal string (e.g. "150.00" for 150 USDC).

chainType

enum<string>

required

Available options:

EVM,

SOLANA

chainId

integer

Target chain id. Use 84532 (Base Sepolia) for sponsored testnet transfers. Required for EVM.

tokenAddress

string

ERC-20 token contract. Omit for a native transfer.

cNGN

boolean

Optional. Set to true to transfer cNGN. Defaults to false.

waitForCompletion

boolean

Optional. true = legacy synchronous mode: hold the request open for the final outcome (201/422) instead of 202 + poll. Defaults to false.

webhookUrl

string<uri>

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.

Maximum string length: 2048

webhookSecret

string

Optional (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.

Required string length: 16 - 256

Response

Created

The response is of type object.

Auth-Edge

Projects

Payments

Products

Subscriptions

Wallet

Tokenization

Blockchain Events

Initiate transfer

Authorizations

Headers

Body

Response