> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiusd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Intent format

> XML schema reference for TIM trading intents.

## Intent structure

TIM intents are expressed in XML. Every intent has a `<type>`, a `<chain_id>`, and type-specific fields.

```xml theme={null}
<intent>
  <type>IMMEDIATE | CONDITIONAL_ENTRY | CLOSE_POSITION</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition>...</condition>
    <action>...</action>
  </entry>
  <exit>...</exit>
</intent>
```

The `<entry>` block defines what triggers the trade and what action to take. The `<exit>` block is optional and defines take-profit/stop-loss conditions.

## Buy semantics

A `<buy>` action spends quote tokens to acquire base tokens.

* `<amount>` is the number of **quote** tokens to spend
* `<quote>` is the token you are spending (address or `AIUSD`)
* `<base>` is the token you are buying (address or symbol)

```xml theme={null}
<action>
  <buy>
    <amount>1</amount>
    <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
    <base>trump</base>
  </buy>
</action>
```

This spends 1 USDC to buy TRUMP on Solana.

<Note>
  `<buy>` does **not** support `<relative>` or percentage amounts. To buy with your full balance, query your portfolio first and use the absolute amount.
</Note>

## Sell semantics

A `<sell>` action sells base tokens to receive quote tokens.

* `<amount>` is the number of **base** tokens to sell
* `<quote>` is the token you receive
* `<base>` is the token you are selling

```xml theme={null}
<action>
  <sell>
    <amount>1000.5</amount>
    <quote>So11111111111111111111111111111111111111112</quote>
    <base>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</base>
  </sell>
</action>
```

### Sell all

Use `<amount>all</amount>` to sell your entire balance:

```xml theme={null}
<action>
  <sell>
    <amount>all</amount>
    <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
    <base>JUP</base>
  </sell>
</action>
```

### Sell percentage

Use `<relative>` to sell a percentage of your balance (sell only):

```xml theme={null}
<action>
  <sell>
    <relative><percentage>50.0</percentage></relative>
    <quote>So11111111111111111111111111111111111111112</quote>
    <base>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</base>
  </sell>
</action>
```

## Default quote token

When the user does not specify a quote token, default to USDC on the target chain. For example:

* "sell TRUMP" uses USDC as quote
* "sell TRUMP for AIUSD" uses AIUSD as quote
* "buy TRUMP with SOL" uses SOL as quote

## Exit strategies

Attach an `<exit>` block to set take-profit and stop-loss conditions:

```xml theme={null}
<exit>
  <conditions>
    <profit_percent>10</profit_percent>
    <loss_percent>5</loss_percent>
  </conditions>
  <logic>OR</logic>
</exit>
```

| Field            | Meaning                                                                 |
| ---------------- | ----------------------------------------------------------------------- |
| `profit_percent` | Sell when PnL reaches +X%                                               |
| `loss_percent`   | Sell when PnL reaches -X%                                               |
| `logic`          | `OR` (default — either condition triggers) or `AND` (both must be true) |

## Intent type examples

### IMMEDIATE — buy with USDC

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <buy>
        <amount>1</amount>
        <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
        <base>trump</base>
      </buy>
    </action>
  </entry>
</intent>
```

### IMMEDIATE — buy with SOL

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <buy>
        <amount>0.001</amount>
        <quote>So11111111111111111111111111111111111111112</quote>
        <base>pump</base>
      </buy>
    </action>
  </entry>
</intent>
```

### IMMEDIATE — sell all

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <sell>
        <amount>all</amount>
        <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
        <base>JUP</base>
      </sell>
    </action>
  </entry>
</intent>
```

### IMMEDIATE — sell percentage

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <sell>
        <relative><percentage>50.0</percentage></relative>
        <quote>So11111111111111111111111111111111111111112</quote>
        <base>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</base>
      </sell>
    </action>
  </entry>
</intent>
```

### IMMEDIATE — buy with exit strategy

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <buy>
        <amount>1</amount>
        <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
        <base>trump</base>
      </buy>
    </action>
  </entry>
  <exit>
    <conditions>
      <profit_percent>10</profit_percent>
      <loss_percent>5</loss_percent>
    </conditions>
    <logic>OR</logic>
  </exit>
</intent>
```

### CONDITIONAL\_ENTRY — event-triggered buy

Register a rule that triggers when PumpFun posts a bullish signal:

```xml theme={null}
<intent>
  <type>CONDITIONAL_ENTRY</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition>
      <event_trigger>
        <event_type>token_listing</event_type>
        <exchange>PUMPFUN</exchange>
        <sub_event_type>PUMPFUN_BULLISH</sub_event_type>
      </event_trigger>
    </condition>
    <action>
      <buy>
        <budget_aiusd>10</budget_aiusd>
        <base_from_event>contract_address</base_from_event>
      </buy>
    </action>
  </entry>
  <exit>
    <conditions>
      <profit_percent>50</profit_percent>
      <loss_percent>30</loss_percent>
    </conditions>
    <logic>OR</logic>
  </exit>
</intent>
```

For `CONDITIONAL_ENTRY`, the buy action uses:

* `<budget_aiusd>` — amount in AIUSD to spend per matching event
* `<base_from_event>` — must be `contract_address` (token resolved from the event)

The response includes a `rule_id`. The rule stays active and triggers on each matching event until cancelled.

### CLOSE\_POSITION — close by position ID

```xml theme={null}
<intent>
  <type>CLOSE_POSITION</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <position_id>pos_abc123</position_id>
</intent>
```

The response includes `cancelled_orders` (any exit orders that were removed) and `realized_pnl`.

## Token addressing

Follow this priority order when specifying tokens:

1. **Contract address provided** — use it directly
2. **Common tokens** — use the known addresses from the table below
3. **Other tokens** — use the symbol (e.g., `trump`, `JUP`). TIM resolves it automatically.

### Common token addresses

| Chain    | Native                                        | USDC                                           | USDT                                           |
| -------- | --------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
| Solana   | `So11111111111111111111111111111111111111112` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` |
| Ethereum | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`  | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`   | `0xdAC17F958D2ee523a2206206994597C13D831ec7`   |
| BSC      | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`  | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d`   | `0x55d398326f99059fF775485246999027B3197955`   |
| Base     | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`  | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`   | —                                              |
| Arbitrum | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`  | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831`   | `0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9`   |

Amounts are always in human-readable decimal format (e.g., `0.170324`), not raw smallest-unit integers.

## CAIP-2 chain IDs

| Chain    | ID                    |
| -------- | --------------------- |
| Solana   | `solana:mainnet-beta` |
| Ethereum | `eip155:1`            |
| BSC      | `eip155:56`           |
| Base     | `eip155:8453`         |
| Arbitrum | `eip155:42161`        |

## AIUSD trading rules

* **Buy AIUSD:** use a `<sell>` action with `<quote>AIUSD</quote>`. Any token can be sold for AIUSD.
* **Sell AIUSD:** use a `<buy>` action with `<quote>AIUSD</quote>`. The base token must be a stablecoin: USDC, USDT, or USD1.

To buy non-stablecoins with AIUSD, run two intents:

1. Convert AIUSD to USDC (`<buy>` with `<quote>AIUSD</quote>` and `<base>` = USDC address)
2. Swap USDC for the target token (`<buy>` with `<quote>` = USDC address)

### Buy AIUSD (sell a token to get AIUSD)

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <sell>
        <amount>100</amount>
        <quote>AIUSD</quote>
        <base>trump</base>
      </sell>
    </action>
  </entry>
</intent>
```

### Sell AIUSD for USDC

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <buy>
        <amount>100</amount>
        <quote>AIUSD</quote>
        <base>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</base>
      </buy>
    </action>
  </entry>
</intent>
```