OTC provider

Restricted partner surface. Every route requires an API key with OTC_PROVIDER; several also require a user session or an explicit provider-team/profile context. These contracts are only for approved liquidity partners and must not be exposed to general integrators.

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

For Header context + OTC_PROVIDER routes, the provider-team context may come from a valid session, both x-profile-id + x-team-id, or an API key scoped to both.

Endpoints#

Method	Path	Auth
`GET`	`/v1/kyc/otc/{otcRequestId}`	Session + `OTC_PROVIDER`
`GET`	`/v1/kyc/{profileId}`	Session + `OTC_PROVIDER`
`GET`	`/v1/kyc/{profileId}/pdf`	Session + `OTC_PROVIDER`
`GET`	`/v1/otc/offers`	`OTC_PROVIDER`
`POST`	`/v1/otc/offers`	Session + `OTC_PROVIDER`
`DELETE`	`/v1/otc/offers/{offerId}`	`OTC_PROVIDER`
`GET`	`/v1/otc/requests`	`OTC_PROVIDER`
`GET`	`/v1/otc/requests/{status}`	`OTC_PROVIDER`
`POST`	`/v1/otc/signatures/create-escrow/provider`	Session + `OTC_PROVIDER`
`POST`	`/v1/otc/{id}/files/provider`	Header context + `OTC_PROVIDER`
`POST`	`/v1/otc/{id}/files/provider/upload-url`	Header context + `OTC_PROVIDER`

Details#

GET `/v1/kyc/otc/{otcRequestId}`#

OTC KYC/KYB PDF Generation API Endpoint


Auth	Session + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

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

Headers#

Header	Required
`x-api-key`	Yes
`Authorization`	Yes — `Bearer <session>`

Path parameters#

Param	Description
`otcRequestId`	Path parameter.

Query parameters#

Field	Type	Required
`type`	enum: `kyc`, `kyb`	No

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, 404, 200.

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

GET `/v1/kyc/{profileId}`#

Retrieving the KYC provider session verification data for approved verification sessions.


Auth	Session + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

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

Headers#

Header	Required
`x-api-key`	Yes
`Authorization`	Yes — `Bearer <session>`

Path parameters#

Param	Description
`profileId`	Path parameter.

Query parameters#

None.

Body#

Not applicable.

Success response#

{
	"success": true,
	"data": {
		"session_id": "session-example",
		"decision": {
			"status": "approved"
		}
	}
}

Errors and statuses#

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

Code	Meaning
`KYC_ROUTE_01`	Invalid API key
`KYC_ROUTE_02`	Invalid session
`KYC_ROUTE_03`	Profile not found
`KYC_ROUTE_04`	No approved verification found
`KYC_ROUTE_05`	The KYC provider API key not configured
`KYC_ROUTE_06`	Failed to retrieve session from the KYC provider
`KYC_ROUTE_07`	Failed to process the KYC provider response

GET `/v1/kyc/{profileId}/pdf`#

Generating PDF reports from the KYC provider for approved verification sessions. Restricted to OTC_PROVIDER API keys.


Auth	Session + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

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

Headers#

Header	Required
`x-api-key`	Yes
`Authorization`	Yes — `Bearer <session>`

Path parameters#

Param	Description
`profileId`	Path parameter.

Query parameters#

Field	Type	Required
`type`	enum: `kyc`, `kyb`	No

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, 404, 200.

Code	Meaning
`VUDY#KYC12`	Invalid API key or missing OTC_PROVIDER permission
`VUDY#KYC13`	Invalid session
`VUDY#KYC14`	Profile not found
`VUDY#KYC15`	No approved verification found
`VUDY#KYC16`	Failed to generate PDF from the KYC provider

GET `/v1/otc/offers`#

Lists OTC offers for the authenticated OTC provider.


Auth	API key + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

Requires x-api-key. No session required.

Headers#

Header	Required
`x-api-key`	Yes
`X-Provider-Team-Id`	Yes

Path parameters#

None.

Query parameters#

Field	Type	Required
`otcRequestId`	UUID	Yes

Body#

Not applicable.

Success response#

{
	"success": true,
	"data": [
		{
			"id": "offer-789",
			"otcRequestId": "otc-123",
			"status": "new",
			"amount": 1000.5,
			"expirationTime": "2026-12-31T23:59:59Z",
			"timeToComplete": 3600,
			"bankId": "bank-456",
			"providerTeamId": "team-uuid"
		}
	]
}

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 `/v1/otc/offers`#

Creates an OTC offer as an OTC provider.


Auth	Session + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

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

Headers#

Header	Required
`x-api-key`	Yes
`Authorization`	Yes — `Bearer <session>`

Path parameters#

None.

Query parameters#

None.

Body#

Field	Type	Required
`providerTeamId`	string	Yes
`otcRequestId`	string	Yes
`amount`	number	Yes
`expirationTime`	string	Yes
`timeToComplete`	integer seconds (1–86400)	Yes
`bankId`	string	Yes
`providerWalletAddress`	string	Yes
`approvalSignature`	string	No

Success response#

{
	"success": true,
	"data": {
		"id": "offer-789",
		"otcRequestId": "otc-123",
		"status": "new",
		"amount": 1000.5,
		"expirationTime": "2024-12-31T23:59:59Z",
		"timeToComplete": 3600,
		"bankId": "bank-456",
		"approvalSignature": "0x123abc...",
		"providerTeamId": "team-uuid",
		"createdAt": "2024-01-01T00:00:00Z"
	}
}

Errors and statuses#

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

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

DELETE `/v1/otc/offers/{offerId}`#

Withdraws (deletes) an OTC offer owned by the provider.


Auth	API key + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

Requires x-api-key. No session required.

Headers#

Header	Required
`x-api-key`	Yes
`X-Provider-Team-Id`	Yes

Path parameters#

Param	Description
`offerId`	Path parameter.

Query parameters#

None.

Body#

Not applicable.

Success response#

{
	"success": true,
	"data": {
		"id": "offer-789",
		"otcRequestId": "otc-123",
		"status": "rejected",
		"amount": 1000.5,
		"expirationTime": "2024-12-31T23:59:59Z",
		"timeToComplete": 3600,
		"bankId": "bank-456",
		"approvalSignature": "0x123abc...",
		"providerTeamId": "team-uuid",
		"updatedAt": "2024-01-01T12: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).

GET `/v1/otc/requests`#

Managing Vudy OTC requests including listing requests filtered by status and team countries.


Auth	API key + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

Requires x-api-key. No session required.

Headers#

Header	Required
`x-api-key`	Yes

Path parameters#

None.

Query parameters#

Field	Type	Required
`country`	comma-separated ISO 3166-1 alpha-2 codes	Yes
`limit`	string	No
`offset`	string	No
`teamId`	string	No

Body#

Not applicable.

Success response#

Envelope wraps an array of provider-facing OTC request rows. Nested objects follow stored resource shapes; reliably known top-level keys per item:

{
	"success": true,
	"data": [
		{
			"otcRequest": {},
			"profileBank": {},
			"team": {},
			"taxInfoSelected": null,
			"buyToken": null,
			"sellToken": null
		}
	]
}

When filtering with teamId, items may also include an offer array for that provider team.

Errors and statuses#

HTTP statuses used by this route: 400, 200.

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

GET `/v1/otc/requests/{status}`#

This module provides API endpoint for retrieving OTC requests filtered by status for a specific provider team.


Auth	API key + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

Requires x-api-key. No session required.

Headers#

Header	Required
`x-api-key`	Yes
`X-Provider-Team-Id`	Yes

Path parameters#

Param	Description
`status`	One of `processing`, `proofRequired`, `proofing`, `proofSubmitted`, `verifying`, `conflict`, `completed`, `cancelled`. Use `/v1/otc/requests` for `new` and `offerReceived`.

Query parameters#

Field	Type	Required
`limit`	string	No
`offset`	string	No

Body#

Not applicable.

Success response#

{
	"success": true,
	"data": [
		{
			"id": "otc-123",
			"status": "processing",
			"type": "buy",
			"buyAmount": 1000.5,
			"sellAmount": 950.0,
			"createdAt": "2024-01-01T00:00:00Z"
		}
	]
}

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 `/v1/otc/signatures/create-escrow/provider`#

Provider Create Escrow Signature Endpoint


Auth	Session + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

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

Headers#

Header	Required
`x-api-key`	Yes
`Authorization`	Yes — `Bearer <session>`

Path parameters#

None.

Query parameters#

None.

Body#

Field	Type	Required
`otcRequestId`	string	Yes
`providerWalletAddress`	string	Yes
`offerAmount`	number	No

Success response#

When the session can sign:

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

Otherwise EIP-712 data for the client wallet:

{
	"success": true,
	"data": {
		"payload": {},
		"signed": false
	}
}

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/{id}/files/provider`#

Confirms files previously uploaded with the matching uploadId and attaches their metadata to the OTC transaction.


Auth	Header context + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

Requires x-api-key plus a provider-team context from a valid session, valid x-profile-id + x-team-id, or an API key scoped to both.

Headers#

Header	Required
`x-api-key`	Yes
`Authorization`	Optional (preferred)
`x-profile-id`	Required when no session
`x-team-id`	Required when no session

Path parameters#

Param	Description
`id`	Path parameter.

Query parameters#

None.

Body#

Field	Type	Required
`uploadId`	string	Yes
`filePaths`	array	Yes
`fileNames`	array	Yes

Success response#

Returns { "success": true, "data": { "tx": <updated transaction> } }. File paths must exactly match the one-hour upload state, each file must exist, and each file is limited to 5 MiB.

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/{id}/files/provider/upload-url`#

Provides signed upload URLs for OTC provider transaction files.


Auth	Header context + `OTC_PROVIDER`
Permissions	`OTC_PROVIDER`
Guide	OTC provider · OTC requester guide

Requires x-api-key plus a provider-team context from a valid session, valid x-profile-id + x-team-id, or an API key scoped to both.

Headers#

Header	Required
`x-api-key`	Yes
`Authorization`	Optional (preferred)
`x-profile-id`	Required when no session
`x-team-id`	Required when no session

Path parameters#

Param	Description
`id`	Path parameter.

Query parameters#

None.

Body#

Field	Type	Required
`fileNames`	array	Yes

Success response#

Returns { "success": true, "data": { "uploadId": "...", "uploadUrls": [...] } }. Keep the uploadId and returned file paths for the confirmation call; upload state expires after one hour.

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).

OTC provider

Endpoints#

Details#

GET /v1/kyc/otc/{otcRequestId}#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

GET /v1/kyc/{profileId}#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

GET /v1/kyc/{profileId}/pdf#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

GET /v1/otc/offers#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

POST /v1/otc/offers#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

DELETE /v1/otc/offers/{offerId}#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

GET /v1/otc/requests#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

GET /v1/otc/requests/{status}#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

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

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

POST /v1/otc/{id}/files/provider#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

POST /v1/otc/{id}/files/provider/upload-url#

Headers#

Path parameters#

Query parameters#

Body#

Success response#

Errors and statuses#

GET `/v1/kyc/otc/{otcRequestId}`#

GET `/v1/kyc/{profileId}`#

GET `/v1/kyc/{profileId}/pdf`#

GET `/v1/otc/offers`#

POST `/v1/otc/offers`#

DELETE `/v1/otc/offers/{offerId}`#

GET `/v1/otc/requests`#

GET `/v1/otc/requests/{status}`#

POST `/v1/otc/signatures/create-escrow/provider`#

POST `/v1/otc/{id}/files/provider`#

POST `/v1/otc/{id}/files/provider/upload-url`#