Skip to main content

Intent API

Turn a natural-language swap request into structured fields for your app or agent.

Public accessCall the endpoint without an API key.
Structured outputRead the tokens, amount and chain from a ParsedIntent.
Wallet signingUse the parsed fields to build an order for your wallet to sign.

Parse a request​

  1. Send the request. Send POST /api/intent to https://ophis.fi with a JSON body containing text.
  2. Read the response. Read intent and entities from data when ok is true.
  3. Handle errors. Read error.code and error.message when ok is false, and honour Retry-After for rate limits.
curl -sS https://ophis.fi/api/intent \
-H 'content-type: application/json' \
-d '{"text":"swap 100 USDC for ETH on Base"}'

Request fields​

SettingValue
Base URLhttps://ophis.fi
EndpointPOST /api/intent
AuthenticationNo API key required
textRequired string, 1–280 characters, case-insensitive
Specificationopenapi.json
{ "text": "swap 100 USDC for ETH on Base" }

Response fields​

A successful request returns 200 OK with a ParsedIntent in data:

{
"ok": true,
"data": {
"intent": "swap",
"entities": [
{ "type": "amount", "value": "100", "raw": "100", "start": 5, "end": 8 },
{ "type": "sellToken", "value": "USDC", "raw": "USDC", "start": 9, "end": 13 },
{ "type": "buyToken", "value": "ETH", "raw": "ETH", "start": 18, "end": 21 },
{ "type": "chain", "value": "base", "raw": "Base", "start": 25, "end": 29 }
]
}
}

ParsedIntent​

FieldTypeDescription
intent"swap" | "unknown"unknown with empty entities for text outside swap requests.
entitiesEntity[]Recognised entities, in any order.

Entity​

FieldTypeDescription
type"sellToken" | "buyToken" | "amount" | "chain"The token you sell, token you buy, amount or chain.
valuestringCanonical form, such as USDC, 0.5 or optimism; token symbols use 2–12 letters/digits with at least one letter, excluding common non-token words.
rawstringA case-insensitive match in the input that the value derives from.
startintegerModel-proposed start offset, inclusive and within the input.
endintegerModel-proposed end offset, exclusive and within the input.
Validate before quoting

Find raw in the input again before using it for highlighting. Resolve each token to its chain and contract address, then request a quote before building an order.

Chain values​

The parser returns these lowercase slugs:

SlugSlug
ethereumarbitrum
arcavalanche
basebnb
gnosisink
lineaoptimism
plasmapolygon
robinhoodunichain

Access controls​

ControlBehaviour
Browser originsA non-null Origin must be https://ophis.fi or https://swap.ophis.fi; other origins receive 403 FORBIDDEN.
Server callscurl and server-side scripts can omit Origin.
Rate limit30 requests per IP per rolling 60-second window; excess requests receive 429 and Retry-After.
Edge cacheIdentical lowercased, trimmed text within an origin bucket is cached for 5 minutes.
Cache hitsx-ophis-cache: hit; counts toward the rate limit and saves an upstream model call.
ParserLibertAI Qwen 3.6 27B on Aleph Cloud, through a Cloudflare Pages Function.
Model accessThe LibertAI key stays on the server; temperature: 0 reduces output variation.

Error codes​

Errors return { "ok": false, "error": { "code", "message" } }:

StatuscodeCause or action
400BAD_INPUTMissing or empty text, text over 280 characters, or invalid JSON.
403FORBIDDENThe supplied Origin is outside the allowlist.
429RATE_LIMITEDMore than 30 requests in 60s from your IP; honour Retry-After.
500UPSTREAMThe server's model key is unset.
502UPSTREAM / INVALID_JSONThe parser was unreachable, returned a non-2xx response or failed schema validation.
504TIMEOUTThe parser exceeded the 5-second timeout.
{ "ok": false, "error": { "code": "RATE_LIMITED", "message": "too many requests" } }

Response headers​

HeaderValue
cache-controlno-store
x-content-type-optionsnosniff
x-frame-optionsDENY
referrer-policyno-referrer
x-ophis-cachehit on a cache hit

Next​