Conventions

Every Infra service follows the same conventions. Learn them once and they apply across the core services (Wallet, Tokenization, and Blockchain Events) and the supporting Auth-Edge, Projects, Payments, Products, and Subscriptions services.

Base URL

All paths are relative to the API host:

https://dev.api.withconvexity.com

Blockchain Events, Products, Subscriptions, and Payments business endpoints are mounted under the /v1 prefix. Blockchain Events endpoints additionally live under /v1/indexer.

Response envelope

Successful responses are wrapped in a consistent envelope:

{
  "status": true,
  "message": "Products retrieved successfully",
  "data": { }
}

Field	Type	Description
`status`	`boolean`	`true` on success, `false` on error.
`message`	`string`	Human-readable summary of the result.
`data`	`object \| array \| null`	The payload. Shape depends on the endpoint.

Error responses use the same envelope with status: false and no data (some validation errors add an errors array). See Errors.

Content types

Send Content-Type: application/json on requests with a body, and Accept: application/json to receive JSON. All request and response bodies are JSON.

Pagination

Three pagination styles are used depending on the service. All are documented per endpoint; this table is the single reference for which service uses which:

Service	Style	Request params
Payments, Subscriptions	Page/pageSize, inline fields	`page`, `pageSize`
Products, Blockchain Events	Page/pageSize, `meta` block	`page`, `limit`
Wallet (transaction history)	Limit/offset	`limit`, `offset`

Page / pageSize
Limit / offset

Page-based (Payments, Subscriptions, Products, Blockchain Events). Request with page and pageSize (or limit) query parameters:

{
  "items": [ ],
  "total": 2,
  "page": 1,
  "pageSize": 20
}

Products and Blockchain Events return a meta block instead of inline fields:

{
  "data": [ ],
  "meta": { "total": 1, "page": 1, "limit": 20, "totalPages": 1 }
}

Cursor/offset (Wallet transaction history). Request with limit and offset:

{
  "items": [ ],
  "pagination": {
    "total": 2,
    "limit": 20,
    "offset": 0,
    "hasMore": false,
    "nextOffset": null
  }
}

Page-size limitsDefaults are page=1 and pageSize/limit=20. Maximums vary by service: Payments and Subscriptions cap at 100; Products caps at 200; Blockchain Events caps at 200.

Data types & formats

Type	Notes
Timestamps	ISO 8601 UTC strings, e.g. `2026-06-17T10:20:08.000Z`.
Monetary amounts (fiat)	Integer major units unless noted, e.g. `1500` = ₦1,500.
Token transfer amounts (Wallet, Tokenization requests/responses)	Decimal strings in the token’s major unit, e.g. `"150.00"` for 150 USDC.
On-chain event amounts (Blockchain Events payloads)	Strings in the token’s smallest unit, as decoded from the raw log, e.g. `"1000000"`.
USD values	Decimal strings, e.g. `"15.871500"`.
Identifiers	UUIDs, Mongo ObjectIds, or integers depending on the resource.
Addresses	Hex strings (`0x...`) for EVM; base58 for Solana.
Enums	Uppercase string constants (e.g. `SUCCESS`, `MONTHLY`, `EVM`).

Terminal status vocabulary

Wallet and Tokenization each run their own on-chain transaction lifecycle, and they settle with different words for the same underlying concept. This is intentional per-service vocabulary, not a bug: check the enum for the specific service rather than assuming one word applies everywhere.

Service	Terminal states	Documented in
Wallet transactions	`COMPLETED`, `FAILED`	Wallet overview
Tokenization transactions	`CONFIRMED`, `FAILED`	Tokenization overview

Both also pass through a PENDING state first; see each overview for the full lifecycle.

Network identifiers

Wallet, Tokenization, and Blockchain Events each identify chains differently. There is no unified scheme today, so use the mapping below rather than assuming a value from one service works in another:

Service	Scheme	Example
Wallet	`chainType` (`EVM` or `SOLANA`) plus a numeric `chainId` for EVM chains	`{ "chainType": "EVM", "chainId": 8453 }`
Tokenization	Short chain code in the `chain` field	`"BASE"`
Blockchain Events	Short network code in the `network` field, one of `ATC`, `BSC`, `ETH`, `BASE`, `POL`, `SOL`, `LISK`	`"BASE"`

Confirmed crosswalk for the chains Wallet currently supports (see Get supported chains for the live, authoritative list):

Chain	Blockchain Events / Tokenization code	Wallet `chainType` + `chainId`
Base	`BASE`	`EVM`, `8453`
BNB Smart Chain	`BSC`	`EVM`, `56`
Solana	`SOL`	`SOLANA`, none (chain is implied by `chainType`)

Wallet’s supported-chains list does not currently confirm coverage for every network Blockchain Events and Tokenization expose (ATC, ETH, POL, LISK). Don’t assume a Blockchain Events/Tokenization network code has a corresponding Wallet chainId until you see it on Get supported chains.

Webhook signatures

Wallet and Blockchain Events both sign webhook deliveries, but with different schemes. Verify against the correct one for the service you’re integrating:

	Wallet (transfer/sign outcomes)	Blockchain Events (on-chain events)
Header(s)	`x-wallet-signature`, `x-wallet-timestamp`	`X-Indexer-Signature`
MAC input	`"<timestamp>.<rawBody>"`	Raw request body
Secret source	You supply your own `webhookSecret` in the request	Server-issued `signingSecret`, returned once on create/rotate
Retries	4 attempts (1s / 5s / 15s backoff, 10s timeout each)	Retried on non-2xx or timeout; inspect and replay via delivery logs (no fixed attempt/backoff schedule is published)

See Outcome webhook and Blockchain Events webhooks & capabilities for the full verification code for each.

Idempotency

Value-moving wallet operations require an Idempotency-Key request header so a retried request never executes twice:

Endpoint	Header
Initiate transfer (`POST /v1/wallet/transaction/`)	`Idempotency-Key`, required
Sign transaction (`POST /v1/wallet/hd/sign`)	`Idempotency-Key`, required

Generate a unique key per operation (a UUID works well) and send it on the request:

curl -X POST https://dev.api.withconvexity.com/v1/wallet/transaction \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0c1d2e3f-4a5b-6c7d-8e9f-001122334455" \
  -d '{ "fromAddress": 0, "toAddress": "0x...", "amount": "150.00", "chainType": "EVM", "chainId": 8453 }'

If a request is retried with the same key (after a network timeout, for example), the server returns the original result instead of submitting a second transfer or signature. Reuse a key only when retrying the same operation; use a fresh key for each new one.

Send a unique key (a UUIDv4 works well) per operation. Reuse a key only when retrying the same request; every new operation must use a fresh key.

Rate limiting

Endpoints are throttled. When you exceed a limit you receive 429 Too Many Requests:

{
  "status": false,
  "message": "Too many requests. Please try again later.",
  "retryAfter": 42
}

The retryAfter field (seconds) tells you when to retry. Back off and retry after that interval. The token endpoint is limited to 30 requests/minute/IP.

Overview

Getting Started

Guides

Changelog

Base URL

Response envelope

Content types

Data types & formats

Terminal status vocabulary

Network identifiers

Webhook signatures

Idempotency

Rate limiting

​Base URL

​Response envelope

​Content types

​Pagination

​Data types & formats

​Terminal status vocabulary

​Network identifiers

​Webhook signatures

​Idempotency

​Rate limiting

Base URL

Response envelope

Content types

Pagination

Data types & formats

Terminal status vocabulary

Network identifiers

Webhook signatures

Idempotency

Rate limiting