---
title: Overview
description: Services, headers, conventions, and status codes for the Hular gRPC API.
---

import { API_URL, API_JSON_URL, PROTO_URL } from "/snippets/vars.mdx";

Two services, one endpoint at {API_URL}, over gRPC, gRPC-web, and JSON at {API_JSON_URL}. The protobuf definition at {PROTO_URL} is the contract; these pages describe it.

Every method has a playground. The three quote methods have theirs inline on this reference; the rest are under **Try it** in the sidebar. Send runs against mainnet; see [Transports](/integration/transports).

## Services

<CardGroup cols={2}>
  <Card title="hular.v1.HularApi" icon="globe">
    Public. Quoting, catalog, chains, and order state. Optional API key.
  </Card>
  <Card title="hular.v1.PartnerApi" icon="user-lock">
    Partner-scoped. Sign-in, API keys, referral claims. Requires a session.
  </Card>
</CardGroup>

## Methods

| Method | Purpose |
| --- | --- |
| [`GetQuote`](/api-reference/get-quote) | Price and persist a trade, returning a depositable quote hash. |
| [`PreviewQuote`](/api-reference/preview-quote) | Price without persisting. |
| [`GetSwapInstructions`](/api-reference/get-swap-instructions) | Aggregator calldata for a quote with a source swap. |
| [`GetOrder`](/api-reference/orders#getorder) | Full detail for one quote hash. |
| [`Search`](/api-reference/orders#search) | Resolve an order from any of its hashes. |
| [`SearchAddress`](/api-reference/orders#searchaddress) | Orders touching an address. |
| [`ListOrders`](/api-reference/orders#listorders) | Paged orders for an address. |
| [`ListRecentOrders`](/api-reference/orders#listrecentorders) | Paged recent orders, protocol-wide. |
| [`SubmitGaslessOrder`](/api-reference/gasless) | Submit a signed gasless deposit for operator relay. |
| [`ListTokens`](/api-reference/catalog#listtokens) | Every quotable token. |
| [`GetTokenInfo`](/api-reference/catalog#gettokeninfo) | One token's metadata. |
| [`GetChains`](/api-reference/catalog#getchains) | Chain status, limits, and explorer templates. |
| [`PartnerApi`](/api-reference/partner) | Fourteen partner-scoped methods: sessions, keys, referrals, funding. |

## Headers

| Header | Applies to | Value |
| --- | --- | --- |
| `x-api-key` | `HularApi` | Your API key. Optional; without it the request is rate limited per IP and quotes carry extra spread. |
| `authorization` | `PartnerApi` | `Bearer <session token>` from `VerifyLoginCode`. |

## Conventions

| Kind | Representation | Example |
| --- | --- | --- |
| Token amount | Decimal string, base units | `"25000000"` |
| USD value | Integer string, micros | `"25000000"` is $25 |
| Basis points | `uint32` | `10` is 0.1% |
| Chain | Lowercase name | `"arbitrum"` |
| EVM address | `0x` hex | `"0xa0b8..."` |
| Solana address | Base58 | `"EPjFW..."` |
| Quote hash | `0x` hex, 32 bytes | `"0x9f2c..."` |
| Timestamp | RFC 3339, microseconds, UTC | `"2026-08-17T10:04:11.482913Z"` |

Field names are `snake_case` on the wire. Generated clients usually expose them as `camelCase`; both appear in these docs, matching whichever surface the example uses.

Amounts are strings because they overflow a JSON number. Parse to a big integer, never a float.

## Status codes

| Code | Meaning |
| --- | --- |
| `INVALID_ARGUMENT` | Malformed or unacceptable request. Change it before retrying. |
| `UNAVAILABLE` | Temporary: inventory, price feed, aggregator, or a disabled chain. Retry with backoff. |
| `RESOURCE_EXHAUSTED` | Rate limited. |
| `UNAUTHENTICATED` | Missing, unknown, or revoked credential. |
| `NOT_FOUND` | No such quote, order, or token. |
| `FAILED_PRECONDITION` | The request is well-formed but the state does not allow it: a non-gasless quote sent to `SubmitGaslessOrder`, an empty funding balance, funding not configured. |
| `INTERNAL` | Operator-side failure. |

See [Error handling](/integration/errors) for the messages behind each code.

## Pagination

Listing methods take `limit` and `cursor` and return `next_cursor`. An absent `next_cursor` means the last page. Cursors are opaque base64 and must not be constructed by hand.

## No streaming

Every method is unary. There is no server stream, webhook, or subscription; track orders by polling `GetOrder`. See [Track an order](/integration/track).

## JSON transcoding

The JSON transport maps each method to a REST route under `{API_JSON_URL}/v1/`: read methods are `GET`s whose request fields become query or path parameters, mutating methods are `POST`s with the request message as the body, and key revocation is a `DELETE`. Each method's route is shown on its reference page. Field names stay as the proto defines them, 64-bit integers are decimal strings, and `bytes` fields are base64. A non-OK status becomes an HTTP error with the gRPC code in the body:

```json
{ "code": 3, "message": "unsupported pair", "details": [] }
```

Codes follow the [gRPC status list](https://grpc.io/docs/guides/status-codes/): 3 is `INVALID_ARGUMENT`, 5 `NOT_FOUND`, 8 `RESOURCE_EXHAUSTED`, 14 `UNAVAILABLE`, 16 `UNAUTHENTICATED`.