OTC

Requester OTC surfaces: create and progress requests via /channel/vudy/otc/*, inspect status, check allowances, and produce user signatures. Provider-only routes: OTC provider.

Auth labels match the endpoint index. Envelopes follow Responses and errors.

For Header context routes, profile context may come from a valid session, both profile/team headers, or an API key scoped to both. GET /v1/otc is the exception documented below: it selects only the session profile or the API key’s scoped profile.

Endpoints#

Details#

POST /channel/vudy/otc/create#

Creates an OTC request for the active profile/team context.

Requires x-api-key plus either Authorization: Bearer <session> or an API key scoped to a profile. This handler does not use x-profile-id / x-team-id as its profile selector.

Headers#

Path parameters#

None.

Query parameters#

None.

Body#

Success response#

Envelope wraps the created OTC request resource (DB row). Reliably known top-level keys include:

{
	"success": true,
	"data": {
		"id": "otc-uuid",
		"txId": "tx-uuid",
		"status": "new",
		"type": "buy",
		"buyAmount": 1000.5,
		"sellAmount": 0,
		"buyCurrency": "token-uuid",
		"sellCurrency": "token-uuid",
		"buyChainId": "chain-uuid",
		"sellChainId": "chain-uuid",
		"profileBankId": "bank-uuid",
		"amountUsd": 1000.5,
		"createdAt": "2026-07-28T12:00:00.000Z",
		"updatedAt": "2026-07-28T12:00:00.000Z"
	}
}

Additional row fields (for example idHash, feeInfo, escrowAddress, txs) may be present depending on persistence.

Errors and statuses#

HTTP statuses used by this route: 400, 403, 500, 200, 401.

POST /channel/vudy/otc/{id}/accept-offer#

Accepting an OTC offer. It validates the user signature and creates the escrow contract on-chain.

Requires x-api-key. No session required.

Headers#

Path parameters#

Query parameters#

None.

Body#

Success response#

{
	"success": true,
	"data": {
		"escrowAddress": "0x...",
		"txHash": "0x...",
		"offerId": "offer-456",
		"requestId": "otc-123"
	}
}

Errors and statuses#

HTTP statuses used by this route: 400, 500, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /channel/vudy/otc/{id}/deny-proof#

Denies submitted OTC proof for a request (moves the flow toward conflict when denial succeeds).

Requires x-api-key. No session required.

Headers#

Path parameters#

Query parameters#

None.

Body#

Success response#

{
	"success": true,
	"data": {
		"requestId": "otc-123",
		"splitIndex": 0,
		"reason": "Invalid receipt",
		"txHash": "0x...",
		"status": "conflict"
	}
}

Errors and statuses#

HTTP statuses used by this route: 400, 500, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /channel/vudy/otc/{id}/prepare-proof#

Preparing proof upload on an OTC request. It generates signed URLs for uploading proof files to cloud storage.

Requires x-api-key. No session required.

Headers#

Path parameters#

Query parameters#

None.

Body#

Success response#

{
	"success": true,
	"data": {
		"uploadUrls": [
			{
				"fileName": "receipt.pdf",
				"signedUrl": "https://storage.googleapis.com/...",
				"expiresAt": "2024-01-01T01:00:00Z",
				"filePath": "otc-proofs/otc-123/..."
			}
		],
		"uploadId": "upload_1234567890_abc",
		"splitIndex": 0
	}
}

Errors and statuses#

HTTP statuses used by this route: 400, 500, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /channel/vudy/otc/{id}/reject-offer#

Rejecting an OTC offer. It includes authorization checks to ensure only the OTC request creator’s team can reject offers.

Requires x-api-key. No session required.

Headers#

Path parameters#

Query parameters#

None.

Body#

Success response#

{
	"success": true,
	"data": {
		"offerId": "offer-456",
		"status": "rejected"
	}
}

Errors and statuses#

HTTP statuses used by this route: 400, 403, 500, 404, 200, 401.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /channel/vudy/otc/{id}/submit-proof#

Submitting proof on an OTC request. It processes uploaded proof files and submits approval transaction to blockchain.

Requires x-api-key. No session required.

Headers#

Path parameters#

Query parameters#

None.

Body#

Success response#

{
	"success": true,
	"data": {
		"requestId": "otc-123",
		"splitIndex": 0,
		"txHash": "0x..."
	}
}

Errors and statuses#

HTTP statuses used by this route: 400, 500, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /channel/vudy/otc/{id}/verify-proof#

Verifies submitted OTC proof for a request (advances the flow when verification succeeds).

Requires x-api-key. No session required.

Headers#

Path parameters#

Query parameters#

None.

Body#

Success response#

{
	"success": true,
	"data": {
		"requestId": "otc-123",
		"splitIndex": 0,
		"txHash": "0x...",
		"status": "verification sent"
	}
}

Errors and statuses#

HTTP statuses used by this route: 400, 500, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

GET /v1/otc#

Retrieving OTC requests for a profile with comprehensive filtering options.

Requires x-api-key. Use Authorization: Bearer <session> or x-profile-id + x-team-id.

Headers#

Path parameters#

None.

Query parameters#

Body#

Not applicable.

Success response#

{
	"success": true,
	"data": [
		{
			"otcRequest": {
				"id": "otc-123",
				"txId": "tx-456",
				"status": "new",
				"type": "buy",
				"buyAmount": 1000.5,
				"sellAmount": 950.0,
				"createdAt": "2024-01-01T00:00:00Z"
			},
			"tx": {
				"id": "tx-456",
				"status": "pending"
			},
			"buyToken": {
				"symbol": "USDC"
			},
			"sellToken": {
				"symbol": "USDT"
			}
		}
	]
}

Errors and statuses#

HTTP statuses used by this route: 400, 500, 200, 401.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /v1/otc/allowance/check#

Checking ERC20 token allowance for the escrow factory contract. Compares current allowance with required amount.

Requires x-api-key. No session required.

Headers#

Path parameters#

None.

Query parameters#

None.

Body#

Success response#

Standard envelope: { "success": true, "data": <resource> }. See the linked guide for workflow-specific fields.

Errors and statuses#

HTTP statuses used by this route: 400, 500, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

GET /v1/otc/gating#

OTC Gating Preflight API Endpoint

Requires x-api-key. Use Authorization: Bearer <session> or x-profile-id + x-team-id.

Headers#

Path parameters#

None.

Query parameters#

None.

Body#

Not applicable.

Success response#

Standard envelope: { "success": true, "data": <resource> }. See the linked guide for workflow-specific fields.

Errors and statuses#

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

GET /v1/otc/proof/{requestId}#

Returns time-limited signed URLs for OTC proof files the caller is authorized to access.

Requires x-api-key. No session required.

Headers#

Path parameters#

Query parameters#

None.

Body#

Not applicable.

Success response#

{
	"success": true,
	"data": {
		"proofUrls": [
			{
				"filePath": "otc-proofs/otc-123/1234567890-receipt.pdf",
				"signedUrl": "https://storage.googleapis.com/...",
				"expiresAt": "2024-01-01T01:00:00Z"
			}
		]
	}
}

Errors and statuses#

HTTP statuses used by this route: 400, 403, 500, 404, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /v1/otc/signatures/approve#

Approves ERC-20 tokens for the OTC escrow factory. With a session that can sign, the API may submit the approval; otherwise it returns transaction data for the client to sign and send.

Requires x-api-key and Authorization: Bearer <session>.

Headers#

Path parameters#

None.

Query parameters#

None.

Body#

Success response#

Standard envelope: { "success": true, "data": <resource> }. See the linked guide for workflow-specific fields.

Errors and statuses#

HTTP statuses used by this route: 400, 500, 200, 401.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /v1/otc/signatures/approve-split#

Generates EIP-712 data for approving escrow splits. With a session that can sign, the API may complete signing; otherwise it returns EIP-712 typed data for the client wallet.

Requires x-api-key and Authorization: Bearer <session>.

Headers#

Path parameters#

None.

Query parameters#

None.

Body#

Success response#

Standard envelope: { "success": true, "data": <resource> }. See the linked guide for workflow-specific fields.

Errors and statuses#

HTTP statuses used by this route: 400, 403, 500, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /v1/otc/signatures/create-escrow/user#

Generates EIP-712 data for user escrow approval. With a session that can sign, the API may complete signing; otherwise it returns EIP-712 typed data for the client wallet.

Requires x-api-key and Authorization: Bearer <session>.

Headers#

Path parameters#

None.

Query parameters#

None.

Body#

Success response#

{
	"success": true,
	"data": {
		"signature": "0x123abc...",
		"signed": true
	}
}

Errors and statuses#

HTTP statuses used by this route: 400, 403, 500, 404, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

POST /v1/otc/signatures/deny-split#

Generates EIP-712 data for denying escrow splits. With a session that can sign, the API may complete signing; otherwise it returns EIP-712 typed data for the client wallet.

Requires x-api-key and Authorization: Bearer <session>.

Headers#

Path parameters#

None.

Query parameters#

None.

Body#

Success response#

Standard envelope: { "success": true, "data": <resource> }. See the linked guide for workflow-specific fields.

Errors and statuses#

HTTP statuses used by this route: 400, 403, 500, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).

GET /v1/otc/txs#

Retrieving OTC transactions with details and offers for profiles or teams.

Requires x-api-key. Use Authorization: Bearer <session> or x-profile-id + x-team-id.

Headers#

Path parameters#

None.

Query parameters#

Body#

Not applicable.

Success response#

Standard envelope: { "success": true, "data": <resource> }. See the linked guide for workflow-specific fields.

Errors and statuses#

HTTP statuses used by this route: 400, 500, 200.

Typical failures: 403 (API key/permissions), 401 (session/context), 400 (validation), 429 (rate limit).