API Docs v2

Integrate Obsidian swap routing into your project and unlock quest tracking for approved middleman contracts on Cronos.

Welcome to the Powered by Obsidian integration guide.

This documentation is for third-party projects that want to:

• Route swaps through Obsidian's aggregator

• Display Obsidian's whitelisted token list and logos

• Earn quest tracking attribution for their users when routing through approved middleman contracts

Note. This is a public partner guide. It only covers supported external integration flows and onboarding requirements.

AI-friendly by design. The endpoint summaries, request bodies, and examples in this guide are structured so they can be handed directly to your editor or coding assistant with minimal rewriting. See Section 5 for prompts and workflows.

Quick Reference

Environment

Item	Value
Base URL	https://api.obsidian.finance
Cronos chain ID	25
Native token placeholder	0x0000000000000000000000000000000000000000
WCRO	0x5C7F8A570d578ED84E63fdFA7b1eE72dEae1AE23
Obsidian router	0x1189331089b6ca8beA989C1F2fFd0EfAdCd33a69

Capabilities

Capability	Status	Notes
Direct swap integration	✅ Supported	Public quote and calldata routes
Public token list and logos	✅ Supported	Helper route for token pickers and branding
Quest tracking for approved middleman contracts	🔒 Supported (gated)	Requires review and a partner API key
Custom dual-recipient partner fee splitting	⛔ Not in public flow	Not documented here

Endpoint Summary

Purpose	Method	Route
Get quote	POST	/:chainId/v1/getquote
Build swap calldata	POST	/v1/getswap
Get public token list	GET	/:chainId/v1/whitelisted-tokens
Submit partner tx hashes for quest tracking	POST	/v1/partners/trades/ingest

1. Direct Swap Integration

The end-to-end partner swap flow is three steps:

1. Call POST /:chainId/v1/getquote

2. Call POST /v1/getswap

3. Broadcast the returned router transaction

The currently documented execution path is EXACT_INPUT.

1.0 Workflow Overview

Your App      ──▶ POST /:chainId/v1/getquote       ──▶ Obsidian Quote API
              ◀── quote, routes, gas estimate      ◀──

Your App      ──▶ POST /v1/getswap                 ──▶ Obsidian Calldata API
              ◀── calldata, routerAddress, value   ◀──

Your User     ──▶ signs and broadcasts transaction ──▶ Cronos

Your Backend  ──▶ POST /v1/partners/trades/ingest  ──▶ Obsidian Quest Tracking
              ◀── processed / skipped / failed     ◀──

1.1 Get Quote

Route

POST /25/v1/getquote

Request body

{
  "currency": {
    "address": "0x7A86f7f7cF2F08E8D4B7C13C7C6F54C5B8d38fA8",
    "decimals": 18,
    "symbol": "TOKEN",
    "name": "Example Token"
  },
  "tradeType": 0,
  "amount": {
    "currency": {
      "address": "0x0000000000000000000000000000000000000000",
      "decimals": 18,
      "symbol": "CRO",
      "name": "Cronos"
    },
    "value": "150000000000000000000"
  },
  "maxSplits": 0
}

Request notes

• Use tradeType: 0 for exact-input quoting.

• Use the zero address 0x0000...0000 for native CRO.

• amount.value must be the raw integer amount in smallest units.

• maxSplits: 0 is the simplest default.

Response highlights

Field	Meaning
fee	Quote fee metadata
gasEstimate	Estimated gas for the quoted route
inputAmount	Effective input amount
outputAmount	Effective output amount
routes	Route breakdown used for execution
tradeType	Returned trade type metadata

Implementation notes. The quote fee currently resolves to 0.004 (0.4%). gasEstimateInUSD exists in the response shape, but should not be treated as authoritative today.

1.2 Build Swap Calldata

Route

POST /v1/getswap

Converts a quote into executable router calldata.

Request body

{
  "trade": {
    "tradeType": "EXACT_INPUT",
    "inputAmount": {
      "currency": {
        "isNative": true,
        "wrapped": {
          "address": "0x0000000000000000000000000000000000000000"
        }
      },
      "quotient": "150000000000000000000"
    },
    "outputAmount": {
      "currency": {
        "isNative": false,
        "wrapped": {
          "address": "0x7A86f7f7cF2F08E8D4B7C13C7C6F54C5B8d38fA8"
        }
      },
      "quotient": "123456789000000000000"
    },
    "routes": [
      {
        "path": [
          {
            "wrapped": {
              "address": "0x5C7F8A570d578ED84E63fdFA7b1eE72dEae1AE23"
            }
          },
          {
            "wrapped": {
              "address": "0x7A86f7f7cF2F08E8D4B7C13C7C6F54C5B8d38fA8"
            }
          }
        ],
        "pools": [
          {
            "address": "0xYourPoolAddress"
          }
        ],
        "inputAmount": {
          "currency": {
            "isNative": true,
            "wrapped": {
              "address": "0x0000000000000000000000000000000000000000"
            }
          },
          "quotient": "150000000000000000000"
        },
        "outputAmount": {
          "currency": {
            "isNative": false,
            "wrapped": {
              "address": "0x7A86f7f7cF2F08E8D4B7C13C7C6F54C5B8d38fA8"
            }
          },
          "quotient": "123456789000000000000"
        },
        "type": "V2"
      }
    ]
  },
  "options": {
    "slippageTolerance": {
      "numerator": "5",
      "denominator": "1000"
    },
    "recipient": "0xYourUserWallet",
    "deadlineOrPreviousBlockhash": "1735689600"
  },
  "chainId": 25,
  "userAddress": "0xYourUserWallet"
}

Mapping rules: quote → trade

From quote	To trade
quote.inputAmount.value	trade.inputAmount.quotient
quote.outputAmount.value	trade.outputAmount.quotient
quote.routes[i].path[j].address	trade.routes[i].path[j].wrapped.address
quote.routes[i].pools[k].address	trade.routes[i].pools[k].address
(constant)	trade.tradeType = "EXACT_INPUT"

Additional rules:

• When a token is native CRO, always set isNative: true.

• Preserving the native zero address at the trade-level input is acceptable.

• Route paths still use wrapped-token hop addresses, so native CRO routes usually begin with WCRO.

• For native output, use the WCRO address anywhere a wrapped output address is required. The API appends the unwrap step internally.

Response highlights

Field	Meaning
calldata	Router calldata to broadcast
value	Native value to send with the tx
routerAddress	Router contract to call
estimatedGas	Estimated gas usage
paths	Path and pool breakdown
recipient	Final swap recipient
multiHopRoute	Whether the route spans multiple hops
feeApplied	Obsidian fee metadata in the built transaction

Broadcasting

Send the user's transaction with:

Tx field	Source
to	routerAddress
data	calldata
value	value

Execution guidance. estimatedGas already includes an API-side safety buffer. If you add more padding client-side, keep it conservative. deadlineOrPreviousBlockhash should usually be a future Unix timestamp. If you omit it, Obsidian defaults the deadline to roughly 10 minutes from request time.

1.3 Compact End-to-End Example

The fastest possible implementation handoff to an engineer or an LLM.

1

Get a quote

curl -s https://api.obsidian.finance/25/v1/getquote \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": {
      "address": "0x6135c840c511a112457d647Aad82a26412a4fa7D",
      "decimals": 18,
      "symbol": "LAZY",
      "name": "Lazy Horse"
    },
    "tradeType": 0,
    "amount": {
      "currency": {
        "address": "0x0000000000000000000000000000000000000000",
        "decimals": 18,
        "symbol": "CRO",
        "name": "Cronos"
      },
      "value": "150000000000000000000"
    },
    "maxSplits": 0
  }'

2

Build swap calldata from the returned quote

curl -s https://api.obsidian.finance/v1/getswap \
  -H 'Content-Type: application/json' \
  -d '{
    "trade": {
      "tradeType": "EXACT_INPUT",
      "inputAmount": {
        "currency": {
          "wrapped": { "address": "0x0000000000000000000000000000000000000000" },
          "isNative": true
        },
        "quotient": "150000000000000000000"
      },
      "outputAmount": {
        "currency": {
          "wrapped": { "address": "0x6135c840c511a112457d647Aad82a26412a4fa7D" },
          "isNative": false
        },
        "quotient": "20028343121762563187544"
      },
      "routes": [
        {
          "path": [
            { "wrapped": { "address": "0x5C7F8A570d578ED84E63fdFA7b1eE72dEae1AE23" } },
            { "wrapped": { "address": "0x3b41B27E74Dd366CE27cB389dc7877D4e1516d4d" } },
            { "wrapped": { "address": "0x6135c840c511a112457d647Aad82a26412a4fa7D" } }
          ],
          "pools": [
            { "address": "0xA51231984ff01F4933a9FA24E8fd143f18ae6772" },
            { "address": "0xD9A74F078418e66BF787036c2a722B3c38704281" }
          ],
          "inputAmount": {
            "currency": {
              "wrapped": { "address": "0x0000000000000000000000000000000000000000" },
              "isNative": true
            },
            "quotient": "150000000000000000000"
          },
          "outputAmount": {
            "currency": {
              "wrapped": { "address": "0x6135c840c511a112457d647Aad82a26412a4fa7D" },
              "isNative": false
            },
            "quotient": "20028343121762563187544"
          },
          "type": "V2"
        }
      ]
    },
    "options": {
      "slippageTolerance": {
        "numerator": "5",
        "denominator": "1000"
      },
      "recipient": "0xYourUserWallet",
      "deadlineOrPreviousBlockhash": "1747804299"
    },
    "chainId": 25,
    "userAddress": "0xYourUserWallet"
  }'

3

Send the transaction

Use the /getswap response as:

Tx field	Source
to	routerAddress
data	calldata
value	value
gasLimit	estimatedGas

Your app or wallet client then signs and broadcasts the transaction normally.

2. Public Token List

Pull token metadata and logos for swap forms, token pickers, and branding.

Route

GET /:chainId/v1/whitelisted-tokens

Example

GET /25/v1/whitelisted-tokens

Returned token fields

Field	Meaning
name	Token name
symbol	Token symbol
address	Contract address
decimals	Token decimals
logoURI	Token logo URL

Rate limits

• Public route

• Rate limited per IP

• Current default limit: 60 requests per minute

3. Quest Tracking for Partner Contracts

If your project uses its own middleman contract and still wants Obsidian quest tracking, onboarding starts with a Discord ticket.

3.1 Open a Discord Ticket With

Required item	Notes
Project name and primary contact	Main point of contact for follow-up
Target chain ID	For example 25 for Cronos
Deployed contract address or addresses	Include all relevant live contracts
Block explorer links	Explorer links for each contract
Verified contract on the relevant explorer	Obsidian can pull contract details from there
Flow description	Explain how your contract routes swaps into Obsidian
One to three real successful tx hashes	Use live successful examples
Expected end-user wallet for each tx hash	Needed for attribution validation
Fee-flow explanation	Include if your contract skims fees before routing

3.2 Contract Requirements

The important requirement is not the outer contract brand or implementation style. The important requirement is that Obsidian can prove the end user and the actual routed swap.

Your contract must:

• Forward a decodable Obsidian router call inside the transaction flow

• Route the swap so the nested Obsidian recipient is the real end user

• Provide a reliable way to attribute the end user

Supported attribution sources

• Transaction sender

• A function argument

• An emitted event argument

Preferred event fields

Field	Priority
user	Required
inputToken	Required
inputAmount	Required
feeAmount	Required
outputToken	Helpful
outputAmount	Helpful

Example event shape

event Swap(
  address indexed user,
  address inputToken,
  uint256 inputAmount,
  uint256 feeAmount,
  address outputToken,
  uint256 outputAmount
);

Important notes. Output token and output amount are helpful, but they are not the main source of truth. Obsidian verifies partner trades primarily from nested router calldata and token transfer logs. Quest volume is tracked from the net amount that actually reached Obsidian after any partner-side skim.

3.3 Partner API Key

After your contract flow is approved, Obsidian will issue a partner API key.

Item	Value
Header name	x-obsidian-partner-key
Header format	clientId.secret
Default rate limit	60 requests per minute per key
Scope	Approved chain IDs and approved contract addresses

3.4 Submit Transaction Hashes

Route

POST /v1/partners/trades/ingest

Headers

Implementation note. Call this route from your backend, worker, or serverless function. Do not expose x-obsidian-partner-key in frontend or browser code. Store the key in an environment variable or server-side secret.

x-obsidian-partner-key: clientId.secret
Content-Type: application/json

Request body

{
  "chainId": 25,
  "txHashes": [
    "0x1111111111111111111111111111111111111111111111111111111111111111",
    "0x2222222222222222222222222222222222222222222222222222222222222222"
  ]
}

Request rules

• Maximum 4 unique transaction hashes per request

• Hashes must be standard 0x-prefixed transaction hashes

• Re-submitting the same successful transaction is safe and idempotent

• Default partner-key rate limit is 60 requests per minute unless Obsidian provisions a different limit for your project

Response shape

{
  "partnerProjectSlug": "example-project",
  "partnerKeyId": "abc123",
  "chainId": 25,
  "submittedCount": 2,
  "processedCount": 1,
  "skippedCount": 1,
  "failedCount": 0,
  "results": [
    {
      "txHash": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "status": "processed",
      "message": "Swap details processed successfully."
    },
    {
      "txHash": "0x2222222222222222222222222222222222222222222222222222222222222222",
      "status": "skipped_existing",
      "message": "Transaction already processed."
    }
  ]
}

Result statuses

Status	Meaning
processed	The trade was verified and written into Obsidian trade tracking
skipped_existing	The transaction was already processed earlier
failed	The hash was received but could not be verified for the approved partner scope

4. Final Notes

• Direct swap integration routes are public.

• Partner quest tracking ingestion is authenticated and only enabled after contract review.

• If your project wants quest tracking, provide real sample transactions early. That shortens onboarding more than anything else.

5. Building with AI

This API was designed to be readable by coding assistants. The endpoint summaries, request bodies, mapping rules, and examples are written so that an AI agent can scaffold a working integration with minimal hand-holding.

This section gives you the patterns, prompts, and guardrails to do it well.

5.1 Why This Doc Is AI-Friendly

The structure of this guide is deliberate:

Pattern	Why it matters for AI
Stable endpoint tables	Models can cite exact routes without hallucinating paths
Explicit request bodies	Models can copy the shape instead of guessing field names
Quote-to-trade mapping table	The most error-prone step is spelled out as a direct map
Constant values in tables	Router, WCRO, native placeholder, and chain ID are easy to extract
Compact end-to-end example	Models can use it as a single-shot reference for full flows

When you hand this doc to an assistant, you do not need to re-explain any of these. They are already in a form the model can use.

5.2 Recommended Workflow

A simple loop that works for most partner integrations:

1. Paste the relevant section of this doc into your assistant.
2. Tell it your stack (Next.js, ethers.js, viem, wagmi, etc.).
3. Tell it what you want (quote, swap, token picker, ingest worker).
4. Ask for a single self-contained module first.
5. Have it write a test against the example payloads in Section 1.3.
6. Iterate.

The shorter and more specific the prompt, the better the output.

5.3 Starter Prompts

Copy, adapt, and paste. Each prompt assumes you have also provided the relevant doc section to the assistant.

Quote and Swap (Frontend)

Using the Powered by Obsidian Partner API docs I provided, generate a
TypeScript module for a Next.js app using viem that:

- Accepts an input token, output token, and input amount in human-readable form
- Calls POST /25/v1/getquote with the correct shape
- Maps the response to POST /v1/getswap using the mapping rules in section 1.2
- Returns { to, data, value, gasLimit } ready to pass to a wallet client
- Treats CRO as native using the zero address
- Uses 0.5% slippage as the default

Use exact field names from the docs. Do not invent fields.

Token Picker (Frontend)

Using the Powered by Obsidian Partner API docs, build a React component that:

- Fetches GET /25/v1/whitelisted-tokens on mount
- Renders a searchable token list with logo, symbol, name, and address
- Caches results in memory for the session
- Falls back gracefully if the request fails

Use the exact field names from section 2.

Partner Ingest Worker (Backend)

Using the Powered by Obsidian Partner API docs, write a Node.js worker that:

- Watches our contract for Swap events
- Buffers tx hashes
- Every 30 seconds (or when 4 hashes are buffered) calls
  POST /v1/partners/trades/ingest with the x-obsidian-partner-key header
- Logs processed, skipped, and failed counts
- Respects the 60 req/min rate limit
- Reads the partner key from an env var, never hardcoded

Use exact field names from section 3.4.

Contract Scaffolding (Quest Tracking Onboarding)

Using section 3 of the Powered by Obsidian Partner API docs, write a Solidity
event and a swap function that:

- Emits the preferred event shape with user, inputToken, inputAmount, feeAmount,
  outputToken, outputAmount
- Forwards the swap to the Obsidian router with the end user as the nested recipient
- Skims a 0.25% fee in the input token before forwarding

Make the user attribution work via the indexed `user` argument in the event.

5.4 Guardrails When Building with AI

Coding assistants are excellent at scaffolding and weak at on-chain reasoning. Use these guardrails:

Guardrail	Why
Always verify the router address from this doc	Models sometimes invent or stale-cache addresses
Always confirm the chain ID is 25	Some models default to mainnet-style chain IDs
Always test with small amounts on Cronos first	An incorrect calldata field will silently route wrong
Pin the exact tradeType values	0 is for the quote route, "EXACT_INPUT" is for the swap route
Treat gasEstimateInUSD as informational only	Documented as non-authoritative
Never let an AI agent hold your partner API key	Use a server-side proxy and inject the key from env
Diff AI output against the example payloads in 1.3	Field-by-field comparison catches almost every shape error

5.5 Suggested Project Files for AI-First Builders

If you are starting a new partner integration, this is a clean repo layout that AI assistants tend to handle well:

your-partner-app/
├── docs/
│   └── obsidian-partner-api.md    ← drop this guide in
├── lib/
│   ├── obsidian/
│   │   ├── quote.ts               ← POST /:chainId/v1/getquote
│   │   ├── swap.ts                ← POST /v1/getswap
│   │   ├── tokens.ts              ← GET /:chainId/v1/whitelisted-tokens
│   │   └── mapping.ts             ← quote → trade mapping helpers
├── server/
│   └── ingest-worker.ts           ← POST /v1/partners/trades/ingest
├── contracts/
│   └── PartnerRouter.sol          ← optional middleman contract
└── tests/
    └── obsidian.spec.ts           ← uses the 1.3 example payloads

Point your assistant at this structure and ask it to fill in one file at a time. Small, focused prompts beat one giant prompt every time.

5.6 When To Ask Obsidian Instead Of An AI

Some things an AI cannot answer for you. Open a Discord ticket if:

• You need quest tracking enabled for a custom middleman contract

• You need a higher rate limit than 60 requests per minute

• Your event attribution does not match any of the supported attribution sources

• You see consistent failed statuses in your ingest responses

• You want to discuss flows not documented in this guide

Real sample transactions speed up every one of these conversations.