OrvynDocs

Developers

Swap API

Screened EVM, Solana and NEAR swap routing that returns unsigned transactions.

The Orvyn Swap API is what agents use to trade on EVM chains, Solana and NEAR. It never holds keys: it returns unsigned transactions for the caller's wallet to sign. Every token is screened first, and every route carries Orvyn's fee.

Base URL: https://api.orvyn.cash (GET / lists the endpoints). All endpoints except /v1/chains need Authorization: Bearer <Orvyn API key> and are rate limited per key.

Endpoints

EndpointRoutingBody → result
GET /v1/chainsSupported EVM chains (no key needed)
POST /v1/swap/quoteKyberSwap{ chain, tokenIn, tokenOut, amountIn, policy? } → route, amounts, price impact, GoPlus security, routeSummary
POST /v1/swap/buildKyberSwap{ chain, routeSummary, sender, slippageBps } → unsigned { to, data, value, gas }
POST /v1/solana/orderDFlow{ inputMint, outputMint, amount, slippageBps, userPublicKey, policy? } → quote and a base64 transaction to sign
POST /v1/near/quoteRhea DCL{ tokenIn, tokenOut, amountIn, policy? } → amounts (net of the token's tax), price impact, fee estimate, market summary
POST /v1/near/buildRhea DCL{ tokenIn, tokenOut, amountIn, sender, slippageBps, policy? } → the unsigned NEAR transactions, in order
POST /v1/near/settle{ txHash, sender } → the transactions that complete a swap: the fee, and unwrapping a sell's NEAR

EVM chains: Base, Ethereum, Arbitrum, BNB Chain, Optimism, Polygon and Avalanche. Amounts are in the token's base units, as strings.

Example: quote and build on Base

bash
curl -s https://api.orvyn.cash/v1/swap/quote \
  -H "authorization: Bearer $ORVYN_API_KEY" -H 'content-type: application/json' \
  -d '{"chain":"base","tokenIn":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","tokenOut":"0x532f27101965dd16442e59d40670faf5ebb142e4","amountIn":"10000000"}'

Pass the returned routeSummary to /v1/swap/build with your sender and slippageBps, then sign and send the transaction from sender (approve tokenIn for the router first if needed).

NEAR: trading Nearly tokens

The NEAR route trades Nearly tokens against NEAR on Rhea's DCL exchange (dclv2.ref-labs.near), where every Nearly launch has its pool. One side is NEAR ("near" or "wrap.near"), the other a live, NEAR-paired Nearly launch.

  1. Quote, then build with your sender. You get the transactions to sign, in order: registering sender on the output token if needed, then the swap (for a buy, one transaction to wrap.near that wraps the NEAR and swaps it).
  2. Sign and send them.
  3. Settle with the swap transaction's hash. Orvyn reads the swap's result from the chain and returns what completes it. For a sell, that's unwrapping exactly the wNEAR it delivered, then the fee. For a buy, it's the fee. For a refunded swap (the price moved), no fee is charged; a refunded buy gets its wrapped NEAR unwrapped. Sign and send those too.

A NEAR transaction calls a single contract, so the fee can't ride inside the swap the way it does on EVM. Settling from the swap's own on-chain result keeps it exact: 0.3% of the NEAR spent or received, paid into Orvyn's registry contract.

  • Your fees are recorded under your client ID. Your API key belongs to a client ID that Orvyn registers in the registry. Settle returns a pay_client_fee call with that ID. The ID always comes from your key, never from the request.
  • Settle every swap you build. A key with 5 or more swaps built but not settled in the last 24 hours can't build more until it settles them.
  • Each swap settles once. Settling the same transaction again returns nothing to pay.
  • A refunded swap is settled with no fee, and a refunded buy gets its wrapped NEAR unwrapped.
bash
curl -s https://api.orvyn.cash/v1/near/quote \
  -H "authorization: Bearer $ORVYN_API_KEY" -H 'content-type: application/json' \
  -d '{"tokenIn":"near","tokenOut":"ninu-4.nearlytrade.near","amountIn":"1000000000000000000000000"}'

NEAR tokens are screened on Nearly's data, not GoPlus. The default is a live, NEAR-paired launch with a tax within Nearly's 4% cap. Pass policy: { minLiquidityNear, minHolders, maxTaxPct } to require more.

Token screening

GoPlus checks every token and fails closed: if the check can't run, the swap is refused.

  • EVM tokens fail for: honeypot, can't sell, owner can change balances, pausable transfers, adjustable tax, unverified source, and, unless your policy allows it, proxy and mintable contracts.
  • Solana tokens fail for: freeze authority, balance-mutation authority, closable accounts, transfer hooks, transfer fees, non-transferable tokens, and an active mint authority unless allowed.
  • Deployer history and changeable metadata come back as warnings.

Selling a token that has since become risky is always allowed, so you can exit. This applies on every route.

Fees

The swap fee (0.3% by default) is built into the route: KyberSwap's extraFee on EVM, DFlow's platform fee on Solana. On NEAR it's settled after the swap, as described above. Solana swaps need USDC or SOL on one side, because that's where the fee is taken.

API keys

Contact Orvyn for a key for your app. Each app gets its own key and client ID, with its own rate limit. The client ID is what your NEAR swap fees are recorded under in the registry. Orvyn's own agents use an internal key and pay under their agent IDs.