Skip to main content
Most Multiliquid API routes are public. A user’s wallet signature authorizes swaps, redemptions, and batch orders, and the data and discovery routes need no credential. A credential identifies an organization: it raises the rate allowance, attributes submissions and redemptions to the organization, unlocks the organization’s own lists, and authorizes capital provider operations.

Credentials

A credential is sent as a bearer token in the Authorization header:
A credential in the query string, such as ?api_key=, is an unknown query parameter. The request is rejected with 400 and code INVALID_REQUEST, not 401, and the message points to the Authorization header. A supplied credential never falls back to anonymous access. A credential that fails authentication receives 401 with code UNAUTHORIZED and the header WWW-Authenticate: Bearer. A valid credential without access receives 403: code INSUFFICIENT_SCOPE when an API key lacks the operation’s scope, ORGANIZATION_NOT_SELECTED when an account session selects no organization, on any route it is sent to, or FORBIDDEN when the credential has no access to the organization, the resource, or the operation, such as another organization’s capital provider or a member’s session on a route only admins may use. GET /v1/organization returns the organization a credential acts for, its id and name, for any API key or an account session that selects an organization; a session that selects none receives 403 with code ORGANIZATION_NOT_SELECTED. Delegates shows it.

API keys

Access is by invitation. Once Multiliquid has invited an organization, its members sign in to the Multiliquid account area at carry.multiliquid.xyz/account-management and manage API keys there. Organizations without access request it from their Multiliquid contact.
  • The key’s secret is shown once, when the key is created. A lost secret cannot be recovered, so the key is revoked and replaced.
  • A key has no expiry unless one is chosen when it is created.
  • Each key carries one or more scopes, chosen when it is created. A key never gains a scope later; a personal key loses cp:admin when its owner is demoted.
  • Rotating a key means creating a replacement with the same scopes, moving the integration to it, and then revoking the old key.

Personal and organization keys

A key is owned by one member or by the organization. An organization key, also called a service key, suits a server integration that must keep working when the people who set it up change roles or leave. Expired and revoked keys do not count toward either limit.

Scopes

A scope grants one kind of access. An integration holds only the scopes it uses, so a key that leaks can do no more than its job requires. An account session holds every scope its member’s role permits: a member’s session holds read, trade, and cp:operate, and an admin’s also cp:admin.

Scope by route

GET /v1/redemptions/{redemptionId} and POST /v1/redemptions show the receiver of the organization’s own redemptions only to a credential with read. A key without it is not rejected there; the response omits receiver. On the other public routes, such as quotes, builds, and the data routes, a key of any scope only moves the request to the credentialed rate allowance. A key without a route’s scope receives 403 with code INSUFFICIENT_SCOPE, and nothing changes:
A credentialed POST /v1/submissions or POST /v1/redemptions whose key lacks trade is rejected with INSUFFICIENT_SCOPE. It is not accepted as an anonymous request. An integration that submits on behalf of users either holds a key with trade or sends those requests without a credential.

Organization attribution

A credentialed submission or redemption is recorded under the credential’s organization, and the organization can then list its own:
  • GET /v1/submissions?network= lists the organization’s submissions. It requires a credential, and an API key needs the read scope.
  • GET /v1/redemptions with a credential and neither user nor redemptionId lists the organization’s redemptions in full. An API key needs the read scope for this list; a lookup by user or redemptionId needs no scope.
A capital provider’s batch order routes show the orders placed with its own capital providers, as Batch operations describes.

Rate allowances

A request with a credential is authenticated before it runs and is not counted against its IP address. A personal key or account session counts against 600 requests a minute for its user and 600 a minute for its organization; an organization key counts against the organization’s allowance alone. On the counted routes, each 401 for a supplied credential spends one of the client IP address’s 30 failed authentications a minute. Rate limits gives every allowance.

Errors

UNAUTHORIZED, FORBIDDEN, INSUFFICIENT_SCOPE, and every other code.

Capital providers

The routes that read, cp:operate, and cp:admin unlock.