Building With Definitive

This guide walks you through building an application that serves many users using Definitive's Organization API. Whether you're creating an app, Telegram bot, trading terminal or something else, this guide provides the step-by-step process for integrating Definitive's execution infrastructure.

Overview

You'll leverage Definitive's Organization API to provide your users with professional-grade trading execution. This architecture allows you to:

• Manage multiple user portfolios from a single organization
• Provide institutional-quality execution for users
• Abstract away the complexity of advanced trading and execution
• Execute cross-chain swaps with the same quote → submit flow (Cross-Chain Market Order)
• Maintain self-custody for end users

Step-by-Step Integration

1. Create an Organization

Start by signing up for Definitive to create your organization. This will serve as the parent entity for all your user portfolios.

Visit the Definitive platform and create an account. Once you're logged in, navigate to your organization page:

2. Generate an API Key

Generate an API key that will be used for all API calls. Definitive supports two scopes:

Portfolio-Level API Keys

Use a portfolio-scoped key if you only need to manage a single portfolio.

1. Log into Definitive.
2. Navigate to your organization page.
3. In the Access Type dropdown, select Portfolio.
4. In the Scope dropdown, choose Read-Only or Read-Write.
5. Click Generate New Key.
6. A new key and secret will be generated.
   • The secret is only shown once; please store it securely.
   • If you lose the secret, you will need to generate a new key and secret.

Organization-Level API Keys

Use an organization-scoped key to manage multiple portfolios and execute trades on behalf of your users.

1. Log into Definitive.
2. Navigate to your organization page.
3. In the Access Type dropdown, select Organization.
4. In the Scope dropdown, choose Read-Only or Read-Write.
5. Click Generate New Key.
6. A new key and secret will be generated.
   • The secret is only shown once; please store it securely.
   • If you lose the secret, you will need to generate a new key and secret.

Store these credentials securely in your application.

3. Integrate Organization Endpoints

Use your organization API key to make calls to the /organization endpoints. These endpoints allow you to manage multiple portfolios and execute trades on behalf of your users.

import { AuthHelpers } from "./auth-helpers";
 
// Initialize with your organization credentials
const apiKey = process.env.DEFINITIVE_API_KEY;
const apiSecret = process.env.DEFINITIVE_API_SECRET;
 
// Example: Get organization details and portfolios
const organizationData = await AuthHelpers.signAndSend({
  path: "/v2/organization",
  method: "GET",
  apiKey,
  apiSecret,
});

For detailed authentication setup, see the Making Your First Request guide.

4. Create User Portfolios

For each user who signs up for your application:

4.1 Create a Portfolio

// Create a new portfolio for the user
const portfolio = await AuthHelpers.signAndSend({
  path: "/v2/organization/create-portfolio",
  method: "POST",
  body: {
    portfolioName: `${userId}`,
  },
  apiKey,
  apiSecret,
});
 
const portfolioId = portfolio.portfolioId;

5. Handle User Deposits

When users are ready to start trading, they need to deposit funds into their Definitive vault. Use the Get Deposit Address endpoint to retrieve the vault address for a given chain, then send funds to that address.

Vaults are created automatically if one doesn't already exist for the specified chain.

6. Facilitate Trading

Once users have deposited funds, you can facilitate trading using the quote and order endpoints.

6.1 Get Trading Quote

// Build once and reuse for quote + submit
const externalOrderRequest = {
  type: "market",
  chain: "ethereum",
  targetAsset: "0xA0b86a33E6411F8D7B0681b1a0eb82B1F0d55d7a", // Example token
  contraAsset: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
  qty: "1000",
  orderSide: "buy",
  slippageTolerance: "0.01", // 1%
  maxPriceImpact: "0.01", // 1%
};
 
// Get a quote for the user's trade
const quote = await AuthHelpers.signAndSend({
  path: `/v2/organization/portfolios/${portfolioId}/trade/quote`,
  method: "POST",
  body: externalOrderRequest,
  apiKey,
  apiSecret,
});

6.2 Submit Order

// Submit the order using the quote
const quoteId = quote.quote.quote.id;
 
const order = await AuthHelpers.signAndSend({
  path: `/v2/organization/portfolios/${portfolioId}/trade`,
  method: "POST",
  body: {
    externalOrderRequest,
    quoteId,
  },
  apiKey,
  apiSecret,
});
 
console.log(`Order submitted: ${order.orderId}`);

Reference: Get Quote | Submit Order

Additional Features

Portfolio Management

Monitor and manage user portfolios:

• Get Portfolio Details - View portfolio and vault information
• List Positions - Check user balances and positions
• List Transfers - View deposit/withdrawal history
• Refresh Balance - Force balance updates
• Get Portfolio Fees - Gets fees for a portfolio

Order Management

Track and manage trading activity:

• List Orders - View order history across portfolios
• Get Order Details - Get detailed order information
• Cancel Order - Cancel pending orders

Advanced Trading

Support sophisticated trading strategies:

• Limit Orders: Set specific price targets
• TWAP Orders: Time-weighted average price execution
• Stop Orders: Conditional order execution
• Stop-Loss Orders: Risk management automation
• Take Profit Orders: Automatic profit-taking when price targets are reached

Best Practices

Security

• Store API credentials securely (environment variables, secrets management)
• Never expose API keys in client-side code
• Implement proper error handling and retry logic
• Validate all user inputs before API calls

User Experience

• Provide real-time order status updates
• Show clear deposit instructions and transaction status
• Implement proper loading states during API calls
• Handle network errors gracefully

Portfolio Management

• Regularly refresh balances for accurate position data
• Implement proper pagination for large datasets
• Cache frequently accessed data to reduce API calls
• Monitor order status and notify users of important updates

Getting Help

• Documentation: Comprehensive API reference in this documentation
• Discord: Join our Discord community for support
• Twitter: Follow @definitivefi for updates