Skip to content

Overview

API Authentication Documentation

Connection Details

Gravity Market's gateways are hosted in AWS Tokyo (ap-northeast-1).

To connect to Gravity Market's APIs, use the following endpoints:


Authentication

Gravity Market supports various authentication methods, including user credentials, API Keys, and OAuth. All three authentication methods are powered by session cookies.

1. Exchange Authentication

Gravity Market utilizes a session cookie with a 24-hour expiry for user authentication.

Authentication

curl --location 'https://edge.testnet.grvt.io/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[email protected]",
    "password": "yourpassword"
}'

Authorization

Include the session cookie in every future request.

Google/Microsoft based authentication

GRVT also provides the option of authenticating using Google/Microsoft using the OAuth2 standard.

2. API Keys

API Keys can be provisioned using the GRVT UI at a sub-account level. Each API key must be tagged to a Ethereum address. An API key consists of two parts:

  • Key ID: (e.g. '2WYgf9fKibj9wUB1mMb9BpMgFZn')
  • Wallet Address: a public Ethereum wallet address

Authentication

curl --location 'https://edge.testnet.grvt.io/auth/api_key/login' \
--header 'Content-Type: application/json' \
--header 'Cookie: rm=true;' \
--data '{
    "api_key": "2WYgf9fKibj9wUB1mMb9BpMgFZn"
}'

Authorization

All API keys are provisioned with TRADE permissions at the sub-account level only. Include the session cookie in the header and a EIP-712 signature associated with the given operation in the body for every future request. All APIs can be submitted via the websockets streams using their respective channel names.

Authenticated Endpoints

At launch, all Market Data endpoints will be public, whereas all Trading endpoints will be private. This might, however, change in the future.


Error Object

Errors are expressed as a pair of Error Codes, and Error Messages. Gravity adopts the gRPC error code system given its disambiguity, and wide spread usage.

Errors come in two forms:

  • Generic System Errors
  • API Specific Errors
Generic System Errors

We Adopt the GRPC error code system.

Failed API calls always return an error code. In some APIs, API level error codes will also be returned.

{
    "code": 3,
    "msg":"INVALID_ARGUMENT",
    "api_code": 1001,
    "api_msg": "INVALID_TIME_IN_FORCE"
}
Code Number Description
OK 0 Not an error; returned on success.
CANCELLED 1 The operation was cancelled, typically by the caller.
UNKNOWN 2 Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
INVALID_ARGUMENT 3 The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).
DEADLINE_EXCEEDED 4 The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
NOT_FOUND 5 Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
ALREADY_EXISTS 6 The entity that a client attempted to create (e.g., file or directory) already exists.
PERMISSION_DENIED 7 The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
RESOURCE_EXHAUSTED 8 Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
FAILED_PRECONDITION 9 The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
ABORTED 10 The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
OUT_OF_RANGE 11 The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled in this service.
INTERNAL 13 Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
UNAVAILABLE 14 The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS 15 Unrecoverable data loss or corruption.
UNAUTHENTICATED 16 The request does not have valid authentication credentials for the operation.
API Specific Error Codes
Code Number Description
INVALID_INSTRUMENT 1001 The instrument supplied is not supported by our exchange
INVALID_TIME_RANGE 1002 The time range specified is invalid
INVALID_INTERVAL 1003 The interval specified is invalid
INVALID_LIMIT 1004 The limit supplied is out of range
INVALID_CURSOR 1005 The cursor supplied is invalid
INVALID_DEPTH 1006 The depth specified is invalid
INVALID_RATE 1007 The rate specified is invalid
INVALID_TIME_IN_FORCE 2001 FULL_ORDER_PRICE_IN_LEGS
MARKET_ORDER_WITH_LIMIT_PRICE 2002 Market Order must always be supplied without a limit price
LIMIT_ORDER_WITHOUT_LIMIT_PRICE 2003 Limit Order must always be supplied with a limit price
OCO_ORDER_WITHOUT_OCO_LIMIT_PRICE 2004 One-Cancels-Other Order must always be supplied with an oco limit price
INSUFFICIENT_TAKER_FEE 2005 Signed Taker Fee lower than Account eligibility
INSUFFICIENT_MAKER_FEE 2006 Signed Maker Fee lower than Account eligibility
POST_ONLY_WHEN_TAKER_ORDER 2007 Post Only can only be set to true for GTT/AON orders
LEGS_EMPTY 2008 Order must contain at least one leg
LEGS_NOT_SORTED 2009 Order Legs must be sorted by Derivative.Instrument/Underlying/BaseCurrency/Expiration/StrikePrice
INACTIVE_DERIVATIVE 2010 Order Legs contain one or more inactive derivative
NUM_CONTRACTS_UNDER_MIN_SIZE 2011 Order size smaller than min size
NUM_CONTRACTS_UNDER_MIN_BLOCK_SIZE 2012 Order size smaller than min block size in block trade venue
ORDER_SIGNATURE_UNAUTHORIZED 2013 Order signature is from an unauthorized signer
ORDER_SIGNATURE_EXPIRED 2014 Order signature has expired
ORDER_SIGNATURE_DOES_NOT_MATCH_PAYLOAD 2015 Order signature does not match payload
CLIENT_ORDER_ID_OVERLAPS 2016 Client Order ID overlaps with existing active order
INVALID_TRIGGER_CONDITION 2017 Usage of an invalid trigger condition
INVALID_TRIGGER_PRICE 2018 Usage of an invalid trigger price
FULL_ORDER_PRICE_IN_LEGS 2019 AON/FOK Order must specify price in legs
PARTIAL_ORDER_PRICE_OUTSIDE_LEGS 2020 GTT/IOC Order must specify price outside legs
ORDER_ID_NOT_FOUND 2101 The order_id supplied is not found
CLIENT_ORDER_ID_NOT_FOUND 2102 The client_order_id supplied is not found
RFQ_ID_NOT_FOUND 3101 The rfq_id supplied is not found
QUOTE_ID_NOT_FOUND 3102 The quote_id supplied is not found
CLIENT_QUOTE_ID_NOT_FOUND 3103 The client_quote_id supplied is not found

Data Types

  • Timestamps are always expressed in uint64 unix nanoseconds (+0 UTC)
  • unsigned integers are used extensively to offer larger usable ranges and on-chain accuracy
  • int32/uint32 are always expressed using unquoted integer literals 1234
  • int64/uint64 are always expressed using quoted numerical string literals "1234"
  • int128/uint128 are always expressed using quoted hexadecimal string literals "0x57d05d11b570fd197b55746070ee051c731ee109b07255eab3c9cf8b6c579d"
  • int256/uint256 are always expressed using quoted hexadecimal string literals "0x57d05d11b570fd197b55746070ee051c731ee109b07255eab3c9cf8b6c579d"
  • eth_addresses are always expressed using quoted hexadecimal string literals but stored as string type to preserve checksummed address information
  • otherwise standard JSON rules apply