Skip to content

API Reference

Explore all nine public integration endpoints, grouped by resource.

Use your deployment origin and an x-api-key integration credential. This reference renders the complete reviewed public OpenAPI 3.1.0 contract. Authentication guide · Download OpenAPI.

Build, order and submit currently return 503 TRADING_NOT_CONFIGURED. The interactive playground is unavailable until a service origin is configured.

Request samples require your origin, key and valid input values. Captured response fixtures are labeled; responses without a verified example show Empty while retaining their schemas.

Pools

Discover pools by mint

GET
/v1/pools

Lists pools discovered by the configured grapl indexer. Supply quoteMint to find a direct pair. Empty results return 200. Catalog inclusion is not a quote or an execution guarantee; use /v1/swap/quote to compare supported pools for an amount.

Authorization

IntegrationKey
headerx-api-key<token>

Integration credential issued to your team. All team keys share the same request quota.

Query Parameters

mint*string

Find indexed grapl pools containing this SPL mint on either side.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address
quoteMint?string

Optional second mint. Restricts discovery to the direct pair, in either order.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address
limit?integer

Maximum pools per page, ordered by pool address.

Range1 <= value <= 100
Default20
cursor?string

Exclusive pool address cursor returned as nextCursor. Pagination is a live catalog view.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address

Response Body

Successful request

application/json
  1. response
success*true
Value intrue
data*
curl -X GET '{GRAPL_API_ORIGIN}/v1/pools?mint=string' \  -H 'x-api-key: {GRAPL_API_KEY}'
Empty

Swaps

Quote the best direct pool

GET
/v1/swap/quote

Provide the input/output mint pair and amount; no pool address is required or accepted. Compares up to 50 indexed candidates using the native engine, including fees and liquidity. ExactIn maximizes output; ExactOut minimizes input. Ties use lexical pool address order. 404 NO_POOLS means the pair is absent; 422 NO_QUOTABLE_POOL means no supported pool can fill the whole amount. RPC failures abort selection with 503, never a partial ranking. Exceeding 50 candidates returns 422 TOO_MANY_POOLS.

Authorization

IntegrationKey
headerx-api-key<token>

Integration credential issued to your team. All team keys share the same request quota.

Query Parameters

inputMint*string

SPL mint to sell. Paired with outputMint for automatic pool selection.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address
outputMint*string

SPL mint to receive; must differ from inputMint.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address
amount*string

Positive u64 token atoms as a decimal string. Input atoms for ExactIn; output atoms for ExactOut. For 6 decimals, 1000000 represents one token.

Match^[1-9][0-9]{0,19}$
Lengthlength <= 20
swapMode?string

ExactIn fixes input and maximizes output; ExactOut fixes output and minimizes input.

Default"ExactIn"
Value in"ExactIn""ExactOut"
slippageBps?integer

Slippage tolerance in basis points: 50 = 0.5%. Sets the returned threshold; does not change which pool has the best nominal quote.

Range0 <= value <= 10000
Default50
taker?string

Optional wallet context for future contextual adapters. Providing an address is not proof of authorization.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address

Response Body

Successful request

application/json
  1. response
success*true
Value intrue
data*
curl -X GET '{GRAPL_API_ORIGIN}/v1/swap/quote?inputMint=string&outputMint=string&amount=string' \  -H 'x-api-key: {GRAPL_API_KEY}'

Captured from the API's isolated selection-test fakes. Test addresses and amounts illustrate the contract, not a market quote. Only the random request ID is normalized.

{  "success": true,  "data": {    "pool": "11111111111111111111111111111111",    "requestId": "isolated-selection-fixture",    "inputMint": "11111111111111111111111111111111",    "outputMint": "So11111111111111111111111111111111111111112",    "inAmount": "1000",    "outAmount": "990",    "otherAmountThreshold": "985",    "swapMode": "ExactIn",    "slippageBps": 50,    "priceImpactPct": null,    "contextSlot": "42",    "expiresAt": "2026-10-12T12:30:10.000Z",    "fees": [      {        "mint": "11111111111111111111111111111111",        "amount": "3",        "kind": "trade"      }    ]  }}

Build unsigned swap instructions

GET
/v1/swap/build

Returns account privileges and instruction bytes for wallet signing when the execution bridge is configured. Currently returns 503 TRADING_NOT_CONFIGURED.

Authorization

IntegrationKey
headerx-api-key<token>

Integration credential issued to your team. All team keys share the same request quota.

Query Parameters

inputMint*string

SPL mint to sell. Paired with outputMint for automatic pool selection.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address
outputMint*string

SPL mint to receive; must differ from inputMint.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address
amount*string

Positive u64 token atoms as a decimal string. Input atoms for ExactIn; output atoms for ExactOut. For 6 decimals, 1000000 represents one token.

Match^[1-9][0-9]{0,19}$
Lengthlength <= 20
swapMode?string

ExactIn fixes input and maximizes output; ExactOut fixes output and minimizes input.

Default"ExactIn"
Value in"ExactIn""ExactOut"
slippageBps?integer

Slippage tolerance in basis points: 50 = 0.5%. Sets the returned threshold; does not change which pool has the best nominal quote.

Range0 <= value <= 10000
Default50
taker*string

Wallet that will sign the swap; required for instruction construction.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address

Response Body

Successful request

application/json
  1. response
success*true
Value intrue
data*
curl -X GET '{GRAPL_API_ORIGIN}/v1/swap/build?inputMint=string&outputMint=string&amount=string&taker=string' \  -H 'x-api-key: {GRAPL_API_KEY}'
Empty

Build an unsigned swap transaction

GET
/v1/swap/order

Execution-bridge contract. Currently returns 503 TRADING_NOT_CONFIGURED; a quote alone does not produce a transaction.

Authorization

IntegrationKey
headerx-api-key<token>

Integration credential issued to your team. All team keys share the same request quota.

Query Parameters

inputMint*string

SPL mint to sell. Paired with outputMint for automatic pool selection.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address
outputMint*string

SPL mint to receive; must differ from inputMint.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address
amount*string

Positive u64 token atoms as a decimal string. Input atoms for ExactIn; output atoms for ExactOut. For 6 decimals, 1000000 represents one token.

Match^[1-9][0-9]{0,19}$
Lengthlength <= 20
swapMode?string

ExactIn fixes input and maximizes output; ExactOut fixes output and minimizes input.

Default"ExactIn"
Value in"ExactIn""ExactOut"
slippageBps?integer

Slippage tolerance in basis points: 50 = 0.5%. Sets the returned threshold; does not change which pool has the best nominal quote.

Range0 <= value <= 10000
Default50
taker?string

Optional wallet context for future contextual adapters. Providing an address is not proof of authorization.

Match^[1-9A-HJ-NP-Za-km-z]{32,44}$
Formatsolana-address

Response Body

Successful request

application/json
  1. response
success*true
Value intrue
data*
curl -X GET '{GRAPL_API_ORIGIN}/v1/swap/order?inputMint=string&outputMint=string&amount=string' \  -H 'x-api-key: {GRAPL_API_KEY}'
Empty

Submit a signed transaction

POST
/v1/swap/submit

Submit a signed transaction. Submission does not establish confirmation or settlement.

Authorization

IntegrationKey
headerx-api-key<token>

Integration credential issued to your team. All team keys share the same request quota.

Request Body

application/json
  1. body
signedTransaction*string
Match^[A-Za-z0-9+/]+={0,2}$
Length4 <= length <= 1644

Response Body

Successful request

application/json
  1. response
success*true
Value intrue
data*
curl -X POST '{GRAPL_API_ORIGIN}/v1/swap/submit' \  -H 'x-api-key: {GRAPL_API_KEY}' \  -H 'Content-Type: application/json' \  -d '{  "signedTransaction": "string"}'
Empty

Transaction status

Read an observed transaction outcome

GET
/v1/swap/status/{signature}

Reads the configured observer. A not_observed result is not proof that a transaction is absent, pending or failed on chain.

Authorization

IntegrationKey
headerx-api-key<token>

Integration credential issued to your team. All team keys share the same request quota.

Path Parameters

signature*string
Match^[1-9A-HJ-NP-Za-km-z]{64,88}$

Response Body

Successful request

application/json
  1. response
success*true
Value intrue
data*
curl -X GET '{GRAPL_API_ORIGIN}/v1/swap/status/string' \  -H 'x-api-key: {GRAPL_API_KEY}'
Empty

Stream transaction status updates

GET
/v1/swap/status/{signature}/events

Stream finalized observations from the configured chain/program. Resume using Last-Event-ID. Not-observed is not proof of absence on chain. Each connection counts as one API request; frames do not. Stop on complete.

Authorization

IntegrationKey
headerx-api-key<token>

Integration credential issued to your team. All team keys share the same request quota.

Path Parameters

signature*string
Match^[1-9A-HJ-NP-Za-km-z]{64,88}$

Header Parameters

last-event-id?string

Last delivered transaction.status event ID. Replays newer persisted events before following live updates.

Match^[1-9][0-9]{0,18}$

Response Body

SSE: snapshot, transaction.status (with id), heartbeat, complete, reconnect or stream-error. Only finalized/failed outcomes are observed currently.

response?stringtext/event-stream
curl -X GET '{GRAPL_API_ORIGIN}/v1/swap/status/string/events' \  -H 'x-api-key: {GRAPL_API_KEY}'
Empty

Usage & limits

Read remaining request quota

GET
/v1/rate-limits

Read-only snapshot for the authenticated key’s team, shared by all its keys. Does not consume trading quota and remains available after exhaustion. Fixed UTC minute and calendar-month windows; concurrent requests can change these values immediately.

Authorization

IntegrationKey
headerx-api-key<token>

Integration credential issued to your team. All team keys share the same request quota.

Response Body

Successful request

application/json
  1. response
success*true
Value intrue
data*
curl -X GET '{GRAPL_API_ORIGIN}/v1/rate-limits' \  -H 'x-api-key: {GRAPL_API_KEY}'
Empty

Read current request consumption

GET
/v1/usage

Read-only snapshot for the authenticated key’s team, shared by all its keys. Does not consume trading quota and remains available after exhaustion. Fixed UTC minute and calendar-month windows; concurrent requests can change these values immediately.

Authorization

IntegrationKey
headerx-api-key<token>

Integration credential issued to your team. All team keys share the same request quota.

Response Body

Successful request

application/json
  1. response
success*true
Value intrue
data*
curl -X GET '{GRAPL_API_ORIGIN}/v1/usage' \  -H 'x-api-key: {GRAPL_API_KEY}'
Empty

Discover pools by mint

Lists pools discovered by the configured grapl indexer.