> For the complete documentation index, see [llms.txt](https://docs.doma.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.doma.xyz/agentic-commerce/skills/trade-tokens.md).
# Trade Tokens
The `trade-tokens` skill lets an AI agent buy or sell **fractionalized domain tokens** across every venue Doma supports: bonding-curve launchpad, post-graduation Uniswap V3, and `sellOnFail` for failed launches. The skill auto-routes based on the token's on-chain state.
## At a glance
| | |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Manifest URL | `https://doma.xyz/.well-known/skills/trade-tokens/SKILL.md` |
| Backing CLI | `@doma-protocol/cli` (`doma swap …`, `doma token …`, `doma quote …`) |
| Wallet modes | `agent` (Privy) and `private-key` |
| Trigger phrases | `buy tokens`, `sell tokens`, `swap tokens`, `trade fractional`, `purchase fractional`, `bonding curve`, `sellOnFail`, `graduated`, `Uniswap`, `post-graduation`, `failed launch` |
## What it does
`doma swap` already auto-detects the right venue. The skill wraps it with a discover → preview → confirm → execute flow:
1. Read the token's on-chain `status` and `tradingVenue` via `doma token --quiet --format json`.
2. Pick the correct venue (Launchpad / Uniswap / sellOnFail) based on the state matrix below.
3. Fetch a quote (`doma quote`) and surface amount-out, price impact, and gas to the user.
4. Confirm before executing.
5. Execute (`doma swap --yes`) and report the on-chain result.
## State × action matrix
This is the routing logic the skill encodes. **Always check `status` first.** A `BOUGHT_OUT` token can have `graduatedAt` set, which would otherwise mislead the agent.
| `status` | `tradingVenue` | `fillPercent` | Buy | Sell |
| ----------------------- | -------------- | ------------- | -------------------------- | -------------------------------- |
| `BOUGHT_OUT` | any | n/a | refuse, already redeemed | refuse, already redeemed |
| `FRACTIONALIZED` | `Launchpad` | < 100% | bonding-curve buy | bonding-curve sell |
| `FRACTIONALIZED` | `Launchpad` | = 100% | refuse, graduation pending | refuse, graduation pending |
| `GRADUATION_FAILED` | `Launchpad` | n/a | refuse, launch failed | `sellOnFail` (fixed-rate refund) |
| `GRADUATION_SUCCESSFUL` | `UniswapV3` | n/a | Uniswap V3 buy | Uniswap V3 sell |
## Prerequisites
* Node.js ≥ 20
* `@doma-protocol/cli` ≥ **0.4.0** for read-only commands; ≥ **0.5.0** for `agent` mode
* A configured wallet (see [Wallet Modes](/agentic-commerce/doma-cli/wallet-modes.md))
* Sufficient input-token balance plus gas
## Example prompt
After installing the skill (see [Discover & Use Skills](/agentic-commerce/agentroot/discover-and-use.md#install-a-skill)):
> "Buy 10 USDC worth of `` token on Doma testnet."
(Mainnet works the same way: drop `testnet` from the prompt and the skill targets Doma Mainnet via your CLI config.)
The agent walks through:
1. Network selection (testnet, since the prompt asked for it).
2. State read (`doma token --testnet --quiet --format json`) → for example `status: GRADUATION_SUCCESSFUL`, `tradingVenue: UniswapV3`.
3. Quote (`doma quote USDC 10`) → expected amount-out, \~0.31% price impact, \~$0.16 gas, 0.5% slippage default.
4. Confirmation prompt with all numbers.
5. Execution (`doma swap USDC 10 --yes --quiet --slippage 50`).
6. Report `Status: Success`, tx hash, block, gas used, and final received amount.
## Cross-references
* [Doma Fractionalization](/api-reference/doma-fractionalization.md): the on-chain primitives the skill operates against.
* Underlying CLI commands: [Commands → swap](/agentic-commerce/doma-cli/commands.md#swap) and [Commands → token](/agentic-commerce/doma-cli/commands.md#token).
* [Wallet Modes](/agentic-commerce/doma-cli/wallet-modes.md): set up agent mode for hands-off swaps.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.doma.xyz/agentic-commerce/skills/trade-tokens.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.