# Direct Organization Integration Guide

Use this guide when the authenticated API user belongs to the organization that will buy, hold, redeem, or transfer WisdomTree fund positions directly.

## Start with these machine-readable resources
- [AI manifest](https://docs.wisdomtreeconnect.com/ai/index.json)
- [Direct-org bundle](https://docs.wisdomtreeconnect.com/ai/direct-org.json)
- [Connect OpenAPI schema (YAML)](https://docs.wisdomtreeconnect.com/openapi/connect.openapi.yaml)
- [Structured docs bundle](https://docs.wisdomtreeconnect.com/docs-data.json)

## Environments
- **Production**: `https://api.wisdomtreeconnect.com` for live orders, real fund movements, and production credentials.
- The production API moved from `app.wisdomtreeconnect.com` to `api.wisdomtreeconnect.com`; the old host works until October 30, 2026. Use the new host, including for `/o/token/`.
- **Sandbox**: `https://api.sandbox.wisdomtreeconnect.com` for integration testing against the full Connect API surface.
- Every Connect endpoint in this guide works against both environments. Swap the base URL to target sandbox.
- Sandbox uses its own API user, `client_id`, and `client_secret`. Production credentials will not authenticate against sandbox, and vice versa. In sandbox, USD orders are approved automatically, so you can test the USD flow end to end without waiting for WisdomTree.

## Prerequisites
- Completed WisdomTree Connect onboarding so the API user credentials and dashboard-generated OAuth client credentials are available
- WisdomTree Connect API username and password
- OAuth client_id and client_secret
- A supported exchange_code and blockchain for the target product
- At least one destination wallet

## Happy path
1. Authenticate with `POST /o/token/` using OAuth2 password grant.
2. Call `GET /api/organizations/me` and capture the direct organization `guid`.
3. Register the settlement wallet through `POST /api/organizations/{organization_guid}/wallets`.
4. Have a second user on your organization approve the wallet, in the Connect UI or with `PATCH /api/organizations/{organization_guid}/wallets/{wallet_guid}`; the user who added it cannot approve it.
5. Create the order with `POST /api/orders/`.
   To validate first without creating anything, send the same body to `POST /api/orders/review`.
   Precision: purchase quantity (USD or USDC) up to 2 decimal places; sale quantity (tokens) up to 18; redemption proceeds truncated to 2; NAV has 8.
6. Track lifecycle progress with `GET /api/orders/all`, `GET /api/orders/{order_reference}`, and `GET /api/orders/{order_reference}/status`.
   To find an order from a blockchain transaction, use `GET /api/orders/hash/{hash}`.
   To check many orders at once, use `GET /api/orders/details/batch?order_references=a,b,c` (up to 100; results in the order sent, matched by position).
   Statements: `GET /api/statements/list` and `GET /api/statements/{statement_id}/download` (Excel file); portfolio workbook: `GET /api/orders/portfolio/download`.
7. Use `GET /api/orders/deposit_address` and `GET /api/orders/on-receipt-wallet/` when building blockchain-triggered flows.
   For instant buy or instant sell (WTGXX and USDC, Ethereum only), send to `destinationAddress` from `GET /api/orders/order-mapping?market_type=secondary`; it is not the on-receipt address.

## Required integration rules
- Keep secrets server-side only and cache tokens safely.
- For non-USD settlement paths, include `wisdomtree_deposit_wallet` in the order request body.
- Do not send `organization_id` in a standard direct-org order flow unless WisdomTree explicitly instructs you to.
- Every wallet must be approved before it is used in an order.
- Use the canonical trailing-slash form for routes that require it, including `/api/accruals/` and `/api/accruals/all/`.

## Access token request example
```bash
curl -X POST "https://api.wisdomtreeconnect.com/o/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=<username>" \
  --data-urlencode "password=<password>" \
  --data-urlencode "client_id=<client_id>" \
  --data-urlencode "client_secret=<client_secret>" \
  --data-urlencode "scope=read write"
```

## Add wallet example
```json
{
  "public_key": "<new_wallet_address>",
  "blockchain": "<blockchain>"
}
```

## Create order example
```json
{
  "exchange_code": "<exchange_code>",
  "quantity": "<quantity>",
  "trade_type": "Purchase",
  "settlement_currency": "<currency>",
  "blockchain": "<blockchain>",
  "settlement_wallet": "<settlement_wallet>",
  "wisdomtree_deposit_wallet": "<wisdomtree_deposit_wallet>"
}
```

## Order lifecycle states
Normal status sequences by order type:
- USDC creation (Purchase settled in USDC): Order Received → Order Approved → Order Valid → Settling - Token Delivered → Settled
- USDC redemption (Sale settled in USDC): Order Received → Order Approved → Order Valid → Settling - Tokens Burned → Settling - Conversion Token Received → Settled
- USD creation (Purchase settled in USD): Order Received → Order Approved → Order Valid → Settling - Token Delivered → Settled
- USD redemption (Sale settled in USD): Order Received → Order Approved → Order Valid → Settling - Tokens Burned → Settling - Wire Delivered → Settled

- `Order Received`: Order accepted by the API and queued for validation.
- `Order Approved`: USDC orders are approved automatically once validation passes. USD purchases are approved manually by WisdomTree after the wire is confirmed in our bank account, then move straight to Order Valid. In sandbox, USD orders are approved automatically.
- `Order Valid`: Order is registered for NAV-based processing and transfer-agent workflow.
- `Settling - Token Delivered`: Settlement step for creations (USD and USDC).
- `Settling - Tokens Burned`: Settlement step for redemptions (USD and USDC).
- `Settling - Conversion Token Received`: Settlement step for USDC redemptions, after tokens are burned.
- `Settling - Wire Delivered`: Settlement step for USD redemptions, after tokens are burned.
- `Settled`: Settlement is complete.
- `Failed`: Not part of the normal sequence. Processing stopped due to validation, funding, or entitlement errors; inspect detail and resubmit.

## Common mistakes
- Building a moderator-specific flow when the integration is actually direct-org only.
- Omitting `wisdomtree_deposit_wallet` for a non-USD subscription or redemption path.
- Using a wallet in an order before it has been approved.
- Polling order status without storing the returned `order_reference`.

Generated from source docs dated 2026-03-13.