Orderly One Dex

Orderly Network: Orderly One DEX

Orderly One (https://dex.orderly.network) is a platform that lets anyone launch a white-label perpetual-futures DEX on Orderly Network — with or without code. It serves as both:

1. A web UI at dex.orderly.network where humans can create, configure, and deploy a DEX through a step-by-step wizard.
2. A REST API that an AI agent or script can call to do the same thing programmatically.

Important: For graduation and broker ID creation — the step that unlocks fee revenue — agents can pay via the x402 HTTP payment protocol (POST /api/graduation/graduate) and register a broker in a single request, no browser needed. The web portal at https://dex.orderly.network/dex remains the easiest path for non-technical users; always inform them this option exists.

Two Launch Paths

See the official builder onboarding guide: https://orderly.network/docs/introduction/getting-started/builder-onboarding

When to Use

• Creating a custom perpetuals DEX
• Managing DEX deployment, domains, or themes
• Handling graduation for fee sharing

Key Concepts

• Broker ID: A unique identifier in the Orderly ecosystem. Starts as "demo" and becomes a real broker ID after graduation. This is how your DEX earns trading fees.
• Graduation: The process of converting a demo DEX into a fee-earning DEX by paying $10-$100 and registering as a broker.
• Template Repository: The GitHub repo that gets forked for each low-code DEX. Contains the Orderly SDK trading frontend.
• One DEX Per User: Each wallet address can create exactly one DEX.

API Base URLs

The API exposes an interactive OpenAPI spec (Scalar) at the root: GET /

Graduation-Supported Chains (Payment)

Mainnet: Ethereum (1), Arbitrum (42161), Base (8453) Testnet: Sepolia, Arbitrum Sepolia, Base Sepolia

API Categories

Use get_orderly_one_api_info MCP tool for full endpoint details.

Create/Update DEX

Both POST /api/dex (create) and PUT /api/dex/{id} (update) use multipart/form-data.

Required Fields

Optional Fields

Chains:

Branding (files):

Theming:

Social:

Auth/Wallet:

Network:

Trading:

Menus:

SEO:

Other:

Response

Create (201): { id, brokerId, brokerName, repoUrl, userId, createdAt }

Update (200): Full DEX object with all fields

Key Workflows

Authentication

Orderly One has its own auth system, separate from the Orderly Network API (api.orderly.org). It uses standard EVM personal_sign (EIP-191) — EVM wallets only (0x addresses).

1. POST /api/auth/nonce with { "address": "0x..." } → { message, nonce }
2. Sign the returned message using personal_sign (EIP-191)
3. POST /api/auth/verify with { "address": "0x...", "signature": "0x..." } → { user: { id, address }, token }
4. Use Authorization: Bearer {token} for all subsequent requests (expires 24h)
5. Validate: POST /api/auth/validate with { "address", "token" } → { valid: true/false }

Note: The graduation "finalize admin wallet" step requires authenticating with the Orderly Network API (api.orderly.org) — a separate system using EIP-712 or Ed25519 signing. See the graduation workflow below.

Create DEX Flow

1. Build multipart/form-data with fields above
2. POST /api/dex → returns { id, brokerId, repoUrl }
3. Poll GET /api/dex/{id}/workflow-status until conclusion: "success"

Graduation (Fee Sharing)

Prerequisites: DEX created with brokerId: "demo" (not already graduated), native USDC on Base, Arbitrum, or Ethereum for the x402 payment.

Step 1 — Get Fee Options:

GET /api/graduation/fee-options → { usdc: { amount }, receiverAddress, payerAddress }

• Low-code: $100 | Custom SDK: $10 — paid in USDC via x402
• payerAddress is the authenticated wallet — it must be the wallet that pays

Step 2 — Pay via x402 (agent-friendly):

POST /api/graduation/graduate?brokerId=…&makerFee=…&takerFee=…&rwaMakerFee=…&rwaTakerFee=… with Authorization: Bearer — pays the fee and registers the broker in a single request.

• First POST returns 402 with a payment-required response header (base64 JSON): one EIP-3009 USDC transferWithAuthorization option per network (base 8453, arbitrum 42161, ethereum 1)
• Sign the EIP-712 authorization and retry with a payment-signature header → 200: transfer settled on-chain (tx hash in the PAYMENT-RESPONSE header, field .transaction), broker registered automatically
• Gasless for the payer — the server relays the settlement; invalid params return 400/401 before charging and cancel the payment
• The EIP-3009 payer wallet must be the same wallet as the Bearer-authenticated account
• x402 clients (@x402/fetch) default spendControls.maxAmountPerPayment to $1 — raise it to cover the fee
• Two-step mode: POST without query params (no Bearer needed — the payment is the auth), then call verify-tx (Step 3) with the settlement tx hash and paymentType: "usdc"
• If the payment settles but graduation fails, reclaim it: POST /api/graduation/refund {txHash, chain} (Bearer, payer wallet)

Step 3 — Verify Transaction (two-step x402 only; skip if auto-finalized):

POST /api/graduation/verify-tx with:

The API verifies: tx exists, sender matches authenticated user, recipient is correct, amount meets fee, tx not reused, brokerId not taken. The broker ID is created here — but graduation is not finished until Step 4.

Step 4 — Register Admin Wallet (required to complete graduation):

EVM Wallet (agents):

1. GET https://api.orderly.org/v1/registration_nonce?address={yourAddress}
2. Sign EIP-712 typed data: { brokerId, chainId, timestamp, registrationNonce } (same brokerId and address you graduated with)
3. POST https://api.orderly.org/v1/register_account with { message, signature, userAddress } → account_id
4. POST /api/graduation/finalize-admin-wallet with an empty JSON body {} + Bearer — binds your own wallet as admin (agents omit the multisig fields)

Solana Wallet:

1. Same flow but chainId: 900900900, sign with Solana wallet, chainType: "SOL"

EVM Multisig/Gnosis Safe:

1. Safe Wallet → Transaction Builder → batch: delegateSigner on Vault contract with [keccak256(brokerId), userAddress]
2. Execute with signer approvals
3. POST /api/graduation/finalize-admin-wallet with { multisigAddress, multisigChainId }

Note: Step 4's registration authenticates with the Orderly Network API (api.orderly.org), not Orderly One — different auth system (EIP-712/Ed25519). finalize-admin-wallet itself uses your Orderly One Bearer token. Confirm with GET /api/graduation/graduation-status until isGraduated: true.

Graduation Status & Fees:

Orderly MCP

This skill references the Orderly MCP server. If not installed, see orderly-onboarding skill for setup.

Tool: get_orderly_one_api_info

• { endpoint: "/api/dex" } - Specific endpoint details
• { category: "graduation" } - All endpoints in a category
• {} - Full API overview

Common Issues

Related Skills

• orderly-onboarding - Account setup and builder onboarding
• orderly-trading-orders - Trading functionality