Omen Developer Portal
API Reference
Wallet Service API
Detailed reference for endpoints, authentication, channels, messages, environment endpoints, and data models in this integration area.
OpenAPI referencev0.2.2Wallets
Omen Wallet Service API
Server-side signing and credential management for the Omen trading platform. **Flows:** - **Prop Trading** — Risk-checked server-side signing via Privy server wallets - **Retail Delegation** — 24h session key delegation for retail users - **Retail Onboarding** — Full Polymarket account setup (Privy embedded wallet + deposit wallet/Safe + credentials) - **Builder HMAC** — HMAC-SHA256 header generation for Polymarket A
Environment endpoints
Local development
http://localhost:8090Local developmentAuthentication
BearerAuthhttpbearer
End-user JWT bearer token for wallet linking endpoints.
ServiceAuthapiKeyX-Service-Secret
Service-to-service shared secret. Required on all non-health endpoints except the JWT-authenticated wallet linking routes, unless `SERVICE_AUTH_REQUIRED=false`.
Endpoints
| Method | Path | Summary | Tags |
|---|---|---|---|
| GET | /health | Liveness probe | Health |
| GET | /health/ready | Readiness probe | Health |
| GET | /internal/wallet/{user_id} | Get linked wallet by user id | Internal |
| GET | /internal/trading-wallet/{user_id} | Get trading wallet by user id | Internal |
| POST | /api/v1/wallet/link | Link a wallet to the authenticated user | Wallet Linking |
| DELETE | /api/v1/wallet/link | Unlink the authenticated user's wallet | Wallet Linking |
| GET | /api/v1/wallet | Get the authenticated user's linked wallet | Wallet Linking |
| POST | /api/v1/polymarket/hmac | Generate builder HMAC headers | HMAC |
| GET | /api/v1/prop/wallets | List prop wallets | Prop Wallets |
| GET | /api/v1/prop/wallets/{wallet_id} | Get wallet details | Prop Wallets |
| POST | /api/v1/prop/wallets/{wallet_id}/sign | Sign order with risk checks | Prop Wallets |
| POST | /api/v1/prop/wallets/{wallet_id}/hmac | Generate HMAC for specific wallet | Prop Wallets |
| GET | /api/v1/prop/wallets/{wallet_id}/positions | Get wallet positions | Prop Wallets |
| GET | /api/v1/prop/wallets/{wallet_id}/pnl | Get wallet PnL | Prop Wallets |
| POST | /api/v1/admin/wallets | Create prop wallet | Admin |
| PUT | /api/v1/admin/wallets/{wallet_id} | Update wallet settings | Admin |
| DELETE | /api/v1/admin/wallets/{wallet_id} | Disable wallet | Admin |
| PUT | /api/v1/admin/wallets/{wallet_id}/rules | Update trading rules | Admin |
| POST | /api/v1/admin/bot-wallets | Provision a bot wallet and API token | Bot Wallets |
| DELETE | /api/v1/admin/bot-wallets/{user_id} | Deactivate a bot wallet | Bot Wallets |
| POST | /api/v1/admin/bot-wallets/{user_id}/rotate-token | Rotate a bot wallet API token | Bot Wallets |
| POST | /api/v1/retail/delegate | Delegate private key for 24h signing | Retail Delegation |
| DELETE | /api/v1/retail/delegate | Revoke delegated key | Retail Delegation |
| GET | /api/v1/retail/delegate/status | Check delegation status | Retail Delegation |
| POST | /api/v1/retail/sign | Sign order with delegated key | Retail Signing |
| POST | /api/v1/retail/onboard | Onboard retail user for Polymarket | Retail Onboarding |
| GET | /api/v1/retail/onboard/status | Check onboarding progress | Retail Onboarding |
| GET | /api/v1/retail/wallet | Get retail wallet info | Retail Account |
| GET | /api/v1/retail/wallet/balance | Get pUSD balance | Retail Account |
| GET | /api/v1/retail/credentials | Get Polymarket API credential metadata | Retail Account |
| POST | /api/v1/retail/credentials/reset | Reset Polymarket credentials | Retail Account |
| GET | /api/v1/retail/approvals | Check token approval status | Retail Account |
| GET | /api/v1/retail/permissions | Get trading permissions for the client location | Retail Account |
| POST | /api/v1/retail/safe/deploy | Deploy Safe contract | Retail Onboarding |
| POST | /api/v1/retail/wallet/register | Register a self-provisioned Privy embedded wallet | Retail Onboarding |
| POST | /api/v1/retail/safe/create | Submit a client-signed SAFE-CREATE deployment | Retail Onboarding |
| POST | /api/v1/retail/safe/execute/prepare | Prepare a SAFE execute for client signing | Retail Onboarding |
| POST | /api/v1/retail/safe/execute/submit | Submit a client-signed SAFE execute | Retail Onboarding |
| POST | /api/v1/retail/deposit-wallet/create | Deploy a Polymarket deposit wallet | Retail Onboarding |
| POST | /api/v1/retail/deposit-wallet/execute/prepare | Prepare a deposit wallet batch for client signing | Retail Onboarding |
| POST | /api/v1/retail/deposit-wallet/execute/submit | Submit a signed deposit wallet batch | Retail Onboarding |
| POST | /api/v1/retail/credentials/prepare | Prepare a ClobAuth challenge for client signing | Retail Onboarding |
| POST | /api/v1/retail/credentials/submit | Submit a client-signed ClobAuth payload | Retail Onboarding |
| POST | /api/v1/retail/polymarket/sign | Sign order via Privy embedded wallet | Retail Signing |
| POST | /api/v1/retail/agentic/sign | Allowlisted Polymarket EIP-712 signing | Retail Signing |
| GET | /api/v1/retail/balances | Get combined balances across venues | Cross-venue |
| GET | /api/v1/retail/deposit-address | Get deposit addresses for all venues | Cross-venue |
| POST | /api/v1/retail/transfer/quote | Get cross-venue transfer quote | Cross-venue |
| POST | /api/v1/retail/transfer/execute | Execute cross-venue transfer | Cross-venue |
| GET | /api/v1/retail/transfer/status/{tx_hash} | Check cross-venue transfer status | Cross-venue |
Data models
ErrorResponseHealthResponseReadinessResponseHmacRequestHmacHeadersHmacResponseWalletLinkRequestWalletLinkResponseWalletGetResponseInternalWalletResponseWalletStatusWalletSummaryPropWalletTradingRulesListWalletsResponseOrderDataSignOrderRequestRiskCheckRiskCheckResultsSignOrderResponsePositionSummaryPositionsResponsePnlResponseCreateWalletRequestCreateWalletResponseCreateBotWalletRequestCreateBotWalletResponseRotateBotWalletTokenResponseUpdateWalletRequestUpdateRulesRequestDelegateKeyRequestDelegateKeyResponseDelegationStatusResponseDelegatedSignRequestDelegatedSignResponseOnboardRetailRequestRetailApiCredentialsRetailApiCredentialMetadataOnboardRetailResponseOnboardingStatusOnboardingStatusResponseRetailWalletResponseRetailSignRequestRetailSignResponseAgenticSignRequestAgenticSignResponseApprovalStatusResponseSafeDeployResponseRegisterRetailWalletRequestRegisterRetailWalletResponseSafeCreateSubmitRequestSafeExecuteTransactionDtoSafeExecutePrepareRequestSafeExecutePrepareResponseSafeExecuteSubmitRequestDepositWalletCreateRequestDepositWalletCreateResponseDepositWalletExecutePrepareRequestDepositWalletExecutePrepareResponseDepositWalletExecuteSubmitRequestDepositWalletExecuteSubmitResponseRelayerSubmitResponseCredentialsPrepareRequestCredentialsPrepareResponseCredentialsSubmitRequestCredentialsSubmitResponseBalanceResponseCredentialResetResponseVenueVenueBalanceBalancesResponsePredictionMarketsDepositInfoPolymarketBridgeDepositAddressesPerpsDepositInfoDepositAddressResponseTransferQuoteRequestBridgeEstimateTransferQuoteResponseTransferExecuteRequestTransferExecuteResponseTransferStatusResponseDexPermissionTradingPermissionsResponse