Give your agent a wallet, not a blank cheque.

Overview

Your agent decides what to trade. Orientim builds the swap, your wallet signs it, and if less than your minimum would arrive, the transaction reverts. Pick a way in:

All but the API check, record and recover each swap for you. You need:

• An API key for the wallet (the MCP server gets its own).
• Your own RPC, and your own Jupiter API key (free).
• A wallet that signs and hands the transaction back: a key file or a signing service.
• Node 20.18 or later.

Quickstart

On Claude Desktop, open orientim.mcpb and answer its questions (MCP server). Otherwise:

1. Get an API key for the wallet: API keys.
2. Install @orientimhq/swap v2.1.0 (source, Apache-2.0).

   npm install --save-exact @orientimhq/swap@2.1.0

3. Check it was built from the GitHub source.

   npm audit signatures

4. Configure (all settings: guide).

   export ORIENTIM_API_URL=https://orientim.com
   export ORIENTIM_API_KEY=ori_...
   export SOLANA_RPC_URL=<your own RPC>
   export JUPITER_API_KEY=<your Jupiter key>
   export ORIENTIM_POLICY=/home/agent/orientim-policy.json

5. Set the owner's limits in a file the agent cannot edit: 50 USDC a swap, 200 a day, only into SOL. A daily limit needs a stateDir.

   {
     "maxAmountIn": { "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": "50000000" },
     "maxAmountInPerDay": { "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": "200000000" },
     "allowedOutputMints": ["So11111111111111111111111111111111111111112"],
     "stateDir": "/home/agent/.orientim-state"
   }

6. Try it without signing.

   npx orientim swap --in EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
     --out So11111111111111111111111111111111111111112 --amount 5000000 \
     --owner <wallet> --dry-run

7. Swap, with the same order id on every retry.

   export ORIENTIM_WALLET_KEYPAIR=/path/to/wallet.json
   npx orientim swap --in EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
     --out So11111111111111111111111111111111111111112 --amount 5000000 --id order-1

8. Make restarts safe: keep the state directory on a lasting disk, run recover on every start, and count only confirmed as done (Results and recovery).

API keys

The wallet signs a message and gets a key for itself. Signing moves nothing. The wallet needs 0.01 SOL; a key lasts 90 days.

export ORIENTIM_API_URL=https://orientim.com
echo '{"wallet": "<address>"}' | npx orientim key-challenge
# sign the bytes of "message" with the wallet, then send "message" unchanged:
echo '{"message": "...", "challenge": "...", "signature": "<base58>"}' | npx orientim key

How a protected swap works

1. Prepare: Orientim builds the transaction and returns it unsigned, with a ticket.
2. Verify: your agent checks the exact bytes on its own RPC.
3. Sign: your wallet signs. Orientim never holds your key.
4. Finalize: Orientim adds its one-time signature and sends it.

A transaction lives about 40 seconds. With fewer than 30 blocks left, prepare again.

Verify before you sign

With the check, even a compromised server cannot make your wallet sign more than you approved, or below your own floor. Without it, you trust Orientim's server with your wallet.

checkPrepared(prepared, intent, yourRpc) returns the problems it finds. Sign only when there are none. The skill and the command line run it for you. It checks:

• The fee, the network fee and your minimum.
• The exact bytes, simulated on your own RPC.
• Rent kept by the route: at most 0.001 SOL (maxRouteCostLamports).

Your minimum must come from your own price, never Orientim's; ownMinimum gets one from Jupiter.

Any language: pipe {"prepared": ..., "intent": {...}} into npx orientim check. Exit 0 means safe to sign.

Your own Jupiter key

With JUPITER_API_KEY set, the skill fetches routes with your key, which never leaves your process. ORIENTIM_OWN_ROUTES=0 (ownRoutes: false in code) uses Orientim's key instead.

Each round counts as one prepare toward the rate limit. Direct API clients: the rounds are in reference/AGENT-API.md.

Results and recovery

The skill and the command line read the result on chain and return an outcome: confirmed, failed, expired, rejected, or unknown (check again before anything new).

For a direct API client

Your wallet's signature is the transaction id. Store it with the ticket before you call finalize; it is how you find out what happened.

Only a swap confirmed on chain is done. sent and unknown mean it may still land.

Orientim keeps no order database. Your store and the chain are the record. The skill keeps that store for you.

• Finalizing the same ticket again is safe: the transaction lands only once.
• Two prepares are two transactions. Use one order id per decision and one swap per wallet at a time.
• Prepare the same swap again only once the signed one can no longer land.

On every start, for a direct API client

1. Load every signed swap not yet settled.
2. Look up each signature on your RPC and record confirmed or failed.
3. Not found: re-send the same bytes, and mark it expired only once the network is past its last valid block.
4. Only then prepare anything new for that wallet.

Authentication

Base URL https://orientim.com. Every request carries an API key:

Authorization: Bearer ori_...

A key prepares swaps for its own wallet only.

Prepare

POST /api/v1/prepare
Authorization: Bearer ori_...
Content-Type: application/json

{
  "owner": "<your wallet address>",
  "inputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "outputMint": "So11111111111111111111111111111111111111112",
  "amountIn": "5000000",
  "minOut": "42400000",
  "slippageBps": 100
}

Answer

All amounts are strings in base units.

A prepare answers within 45 seconds, or 503 unavailable. Bodies may be up to 1 MiB.

Finalize

POST /api/v1/finalize
Authorization: Bearer ori_...
Content-Type: application/json

{ "ticket": "eyJ2Ijox....", "signedTransaction": "<base64, signed by your wallet>" }

Orientim signs and sends. The same ticket again returns the same transaction.

{
  "signature": "5h...",
  "status": "sent",
  "signedTransaction": "<base64, fully signed>",
  "lastValidBlockHeight": "312345678"
}

status: see Results and recovery. To send it yourself (staked RPC, bundle), add "send": false and re-send until it confirms or expires.

Keys

GET /api/v1/keys/challenge?wallet=<address>
→ { "message": "...", "challenge": "...", "expiresAt": "..." }

POST /api/v1/keys
{ "message": "<the message, unchanged>", "challenge": "...", "signature": "<base58 or base64>" }
→ { "key": "ori_...", "wallet": "<address>", "expiresAt": "..." }

• Sign the challenge within 10 minutes.
• Sign only Orientim's key message. Other bytes could be a transaction.
• Keep your key; do not request a new one on every start.

Errors

Every error is { "error": { "code": "...", "message": "..." } }, and nothing was signed or sent. requiresApproval: true means ask the user, do not retry.

Rate limits

• Per wallet: 60 prepare and 30 finalize a minute.
• Per IP address: 120 requests a minute.
• Keys: 30 challenges and 10 keys an hour per IP, 5 keys a day per wallet.
• A 429 carries Retry-After.
• GET /api/health needs no key: 200 when swaps can go through, else 503.

Fees and limits

• 0.25%, inside the transaction, in SOL, USDC or USDT when the swap has one, else the input token (amounts.feeMint).
  • On the input: that share of amountIn.
  • On the output: that share of the enforced minimum. With your own routes, it must be within 1% of Orientim's price.
  • Otherwise: that share of the swap's value, in SOL from the wallet.
• The skill refuses an Orientim fee above 0.25% (maxFeeBps, up to 0.3%) and a network fee above 0.001 SOL.
• Slippage: 0.5% by default, 3% on a Pump.fun curve (slippageBps, 0.1% to 15%).
• Price impact: at most 5% (maxPriceImpactBps, up to 20%).
• The minimum is never more than 20% below Jupiter's price.
• The owner's limits per swap, per day and per token (ORIENTIM_POLICY).
• Smallest swap: about 0.004 SOL or $1, except selling a whole balance.

Tokens and wallets

See supported tokens. Key files and signing services work; sign-and-send-only wallets and multisig vaults do not.

Downloads

• @orientimhq/swap v2.1.0 on npm: library, CLI, MCP server and skill.
• orientim.mcpb: the MCP server for Claude Desktop.
• Verify: gh attestation verify <file> -R orientimhq/orientim-protected-swap, or the sha256 in RELEASE-SHA256SUMS on the release.
• Source on GitHub, Apache-2.0, with a reproducible build.
• Full API reference: reference/AGENT-API.md in the skill folder.