# Offering Manager API

The Bitbond Offering Manager Platform provides a public REST API under `/api/public` that allows you to integrate investor-facing flows into your own applications. You can retrieve offering details, create and manage orders, process payments (SEPA/wire bank transfer, card via <https://www.checkout.com>, stablecoin), integrate identity verification, and manage multi-chain wallet addresses. The API follows RESTful conventions and returns JSON responses.

For issuer onboarding and key management, visit the Offering Manager at <https://om.bitbond.com> and navigate to **Settings > API Access**.

## Generating an API Key

To use certain API endpoints (for integration and automation), you first need to generate an API key:

1. Go to **Settings** in the admin panel at <https://om.bitbond.com/admin/settings>.
2. Scroll to the **API Access** section.
3. Click **Generate New API Key**.
4. Copy the key immediately — it is displayed only once and cannot be retrieved later. Store it securely.

You can generate a new key at any time. Note that generating a new key replaces the previous one — any integrations using the old key will stop working.

## Authentication

Include your API key in the `Authorization` header of every protected API request:

```
Authorization: Bearer YOUR_API_KEY
```

Requests without a valid API key receive a `401 Unauthorized` response.

## Public API Base URL

All public endpoints are available under:

```
https://om.bitbond.com/api/public
```

Tenant-specific data is accessed by passing a `subdomain` query parameter (e.g. `?subdomain=acme-gmbh`), not via separate domains.

## API Documentation (OpenAPI/Swagger)

The full, interactive API reference is available as the [Public API Reference](https://om.bitbond.com/api/docs). This portal provides:

* A complete list of all available endpoints.
* Request and response schemas for each endpoint.
* The ability to try out API calls directly from the browser.
* Authentication setup instructions.

## Available Endpoints

### Offerings

* **GET /offerings/:slug?subdomain=\<tenant\_subdomain>**\
  Retrieve offering details, live fundraising totals, and payment configuration.

  Query parameter:

  * `subdomain` (required): the tenant’s subdomain

  Successful response includes:

  * Core offering fields (`slug`, `name`, `description`, `funding_target`, `hard_cap`, etc.)
  * `documents`: array of `{ id, display_name, requires_agreement }`
  * `discount_tiers`: array of `{ id, min_amount, max_amount, discount_pct, label }`
  * `liveStats`: current totals and progress against fundraising targets
  * `tenantBankDetails`:
    * `bankName`, `accountHolderName`, `iban`, `bic`
  * `paymentConfig`:
    * `hasCheckoutCom` (boolean)
    * `checkoutComPublicKey` (string or `null`)
    * `hasEvmCrypto` (boolean)
    * `hasCustodian` (boolean)
    * `custodianProvider` (string)
    * `acceptedTokens` (array of stablecoin symbols)
    * `acceptedChains` (array of supported blockchain IDs)

  Error cases:

  * `400 Bad Request` if `subdomain` is missing.
  * `403 Forbidden` if the investor’s country (via `CF-IPCountry` header) is blocked for this offering.
  * `404 Not Found` if the tenant or offering is not found, or the offering is not active.

### Documents

* **GET /documents/:docId/download**\
  Download an offering document (PDF) for an active or closed offering. Returns the PDF inline with:
  * `Content-Disposition: inline; filename="<display_name>.pdf"`
  * `Content-Type: application/pdf`

### Token Info

* **GET /token-info?chain=\<chain\_id>\&address=\<contract\_address>**\
  Lookup on-chain token metadata (name, symbol, decimals) for supported networks.

  Query parameters:

  * `chain` (required): the network ID
  * `address` (required): the token contract address

  Successful response:

  * `{ name, symbol, decimals }`

  Error responses may include:

  * `400 Bad Request` for missing or invalid parameters
  * `404 Not Found` if the token or chain is unknown
  * `429 Too Many Requests` when rate limiting
  * Error payload with `error` and `kind` fields for diagnostics

### Order Management

* **POST /orders**\
  Create a new investor order. Request body:

  * `offeringId` (string, required)
  * `fiatAmount` (number, required)
  * `tokenAmount` (number, required)
  * `paymentMethod` (string, one of `bank_transfer`, `checkout_com`, `stablecoin`, required)
  * `walletAddress` (string, optional)
  * `walletChainType` (string, optional)
  * `cryptoNetwork` (string, optional)
  * `agreedDocumentIds` (array of document IDs, optional)
  * `investorProfile` (object, optional) — to collect or update KYC/AML details

  Returns `201 Created` with:

  * `order`: the newly created order object
  * `bankDetails` (for `bank_transfer` payments)
  * `cryptoDepositAddress` (for stablecoin or on-chain payments)
* **GET /orders/investor/portfolio?subdomain=\<tenant\_subdomain>**\
  Retrieve the authenticated investor’s orders for a tenant.

  Query parameter:

  * `subdomain` (string, required)

  Response:

  * `orders`: array of order objects, each including:
    * `cancellationDeadline`
    * `canCancel` (boolean)
  * `walletAddress` (string or `null`): the investor’s primary EVM address
  * `wallets`: map of chain types to addresses (`{ [chainType]: address }`)
* **GET /orders/:referenceCode**\
  Retrieve details for a single order by its reference code. Response includes:
  * All order fields
  * `cancellationDeadline`
  * `canCancel` (boolean)
* **POST /orders/:id/cancel**\
  Cancel a pending order within its allowed cancellation window. Returns the updated order or an error if the window has passed.

### Payment Processing

* **GET /payments/checkout-config?subdomain=\<tenant\_subdomain>**\
  Retrieve the tenant’s Checkout.com public key configuration. Query parameter:

  * `subdomain` (required)

  Response:

  * `publicKey` (string or `null`)
  * `configured` (boolean)
* **POST /payments/checkout-session**\
  Create a Checkout.com payment session for a pending order. Request body:

  * `orderId` (string, required)

  Returns:

  * `sessionId`
  * `sessionToken`
  * `publicKey`
* **POST /payments/checkout-pay**\
  Complete a card payment via Checkout.com using a Frames.js card token. Request body:

  * `orderId` (string, required)
  * `cardToken` (string, required)

  Returns the payment result or error details.

### KYC Workflow

The platform supports two identity verification providers. Configure your preferred provider in **Settings**:

* Sumsub: <https://sumsub.com>
* Blockpass: <https://www.blockpass.org>

Endpoints:

* **POST /kyc/init**\
  Initialize a KYC session for an offering. Request body:

  * `offeringId` (string, required)
  * `investorType` (`individual` or `institutional`, defaults to `individual`)

  Returns provider-specific tokens or SDK configuration.\
  For Sumsub: `{ provider: "sumsub", sdkToken }`.\
  For Blockpass: provider response with redirect or widget parameters.
* **GET /kyc/status**\
  Poll the status of the authenticated investor’s verification. Response:
  * `kyc_status` (`none`, `pending`, `approved`, `rejected`, etc.)
  * `kyc_record_id` (string or `null`)

### Investor Profile & Wallets

* **GET /investor/profile**\
  Fetch the authenticated investor’s profile:

  Response:

  * `profile`: object containing personal and company fields (name, email, address, investor type, etc.), `kyc_status`, `kyc_record_id`
  * `wallets`: map of chain types to `{ address, source }`
  * `walletHistory`: audit trail of wallet address changes
  * `hasConfirmedOrder` (boolean)
* **PATCH /investor/profile**\
  Add, update, or remove a wallet address. Request body:

  * `walletAddress` (string or `null`, required)
  * `chainType` (one of `evm`, `solana`, `stellar`, `xrpl`; defaults to `evm`)

  Records all changes in the audit log and returns:

  * `message`: status message
  * `walletAddress`
  * `chainType`

## Common Use Cases

* Build a custom investor UI powered by offering data, documents, and live stats.
* Integrate investor data, order statuses, or payment sessions with CRM or accounting tools.
* Automate workflows: programmatic order creation, KYC initiation, wallet management.
* Support on-chain stablecoin deposits alongside traditional payment rails.

## API Scope

The public API covers all investor-facing flows, including offering discovery, order management, payment sessions, KYC initiation, and wallet management. It does **not** include administrative operations (use the admin panel for user and tenant management, offering configuration, team settings, and audit exports).

For the complete request and schema reference, see the [Public API Reference](https://om.bitbond.com/api/docs).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bitbond.com/asset-tokenization-suite/offering-manager/offering-manager-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.